Claude Code is only as good as the context you give it. Skills are the cleanest way to package that context: a folder of instructions Claude loads when it needs them, and only then. This post explains what a skill is, why it beats one giant prompt, and how I combine skills with rules in two real templates: ClaudeCode-Hono(opens in new tab) and ClaudeCode-React(opens in new tab).
A skill is a directory under .claude/skills/ with a SKILL.md file. The file starts with a short frontmatter (name, description), followed by the instructions in Markdown. It can also ship extra files: reference docs, rules, assets, evals.
The key idea is progressive disclosure. Claude only sees the description of each skill at the start of a session. The full body is loaded when the task matches that description. You can have twenty skills installed without paying twenty skills' worth of tokens on every prompt.
.claude/skills/create-auth/SKILL.mdmd
---name: create-authdescription: Scaffold and implement authentication in TypeScript/JavaScript apps using Better Auth. Use when users want to add login, sign-up, or authentication.---
# Create Auth Skill
## Phase 1: Planning (REQUIRED before implementation)
Scan the project, then ask the user structured questions...
The description is the most important line. It is the trigger: write it as "what this does" plus "use when…".
Without skills, you have two bad options: repeat yourself in every prompt, or stuff everything into CLAUDE.md until it is huge and ignored. Skills fix both.
Both of my templates split the context into three layers. Each one has a different job and a different loading strategy.
CLAUDE.md# stack, structure, non-negotiables
.claude/
rules/# project-specific conventions, imported with @
hono.md
openapi.md
testing.md
skills/# generic know-how, loaded on demand
create-auth/
SKILL.md (highlighted)
better-auth-best-practices/
···and more files
skills-lock.json# pins installed skills
CLAUDE.md holds decisions that never change: the stack, the folder layout, a "What Claude must never do" list.
rules/ holds detailed conventions specific to my project, imported from CLAUDE.md with @.claude/rules/tables.md.
skills/ holds generic knowledge about a tool or a workflow, reusable in any project.
The React template says it explicitly: the TanStack skills cover the API usage, so CLAUDE.md "only holds project-specific decisions and rules that apply everywhere, so it doesn't repeat what the skills already say."
ClaudeCode-Hono(opens in new tab) is a config for a Hono + Prisma + Better Auth backend. The skills come from the Better Auth team and handle everything auth-related: create-auth, better-auth-best-practices, better-auth-security-best-practices, email-and-password-best-practices and two-factor-authentication-best-practices.
Auth is a perfect skill topic: it is a big, detailed domain, security-sensitive, and only relevant when you touch login. Loading it on every prompt would be wasteful. Loading nothing would let Claude improvise crypto.
What stays out of skills is my architecture. Those are hard rules, written as constraints Claude can check itself:
CLAUDE.mdmd
## What Claude Must Never Do- Instantiate `PrismaClient` outside `src/lib/prisma.ts`- Sign, verify, or decode a session/token by hand — always go through `auth.api.*`- Extract a route handler into a named function — handlers are inline inside `.openapi()`- Let Vitest tests connect to a real database
It also contains a checklist for adding a resource (Prisma model, route file, mounting, tests), so every new endpoint comes out the same shape.
ClaudeCode-React(opens in new tab) targets a back-office frontend with TanStack Router, Query, Form and Table. Each library has its own skill (tanstack-router, tanstack-query, tanstack-form, tanstack-table), next to shadcn, typescript-rules and better-auth-best-practices.
The shadcn skill shows how far a skill can go. It is not a single file: it ships a CLI guide, a registry guide and a rules/ folder (forms, icons, styling, composition), plus an evals/ folder to test that it triggers correctly.
The project-specific part lives in rules/. For example, the table rule states that tables are entirely server-driven and that filters live in the column header, never in a toolbar. A generic tanstack-table skill cannot know that; my rule file can, and it even documents where it departs from the skill.
Say what it does and when to use it. Include the words you would actually type when asking for it.
Keep the body short, link the rest
Put the workflow in SKILL.md and move long references to sibling files, like shadcn/rules/forms.md. Claude reads them only if needed.
Test it
Ask for the task in a fresh session and check the skill triggers. Then ask something unrelated and check it does not.
You can also install community skills instead of writing them. The Hono template pins them in a lock file, which makes the setup reproducible across machines:
Pick the one task you explain most often and turn it into a skill today. Then fork one of the templates, Hono(opens in new tab) or React(opens in new tab), and adapt the CLAUDE.md and rules to your own conventions. The blog you are reading uses the same idea: a write-blog-post skill documents every MDX component, so Claude can publish posts like this one.