You're in Claude Code and you want Claude to be better at your workflows: code review, writing docs, debugging, migrations, whatever your team does every week.
The constraint is boring but real: the context window. Every extra instruction you load competes with the conversation, the code excerpt you just pasted, and the thing you're trying to solve.
Claude skills are a practical answer to that. They’re modular capabilities that extend Claude, but they load only what’s needed, when it’s needed. Instead of dumping a giant playbook into context, skills use lazy evaluation: metadata first, details on demand.
Here’s why that matters—and how to use them well.
What Are Claude Skills?
A skill is a folder of instructions (and optionally scripts and references) that teaches Claude how to perform a specific task. The key difference from other extension methods is who decides when to use it.
With slash commands, you invoke functionality directly: /review-pr 123. You’re in control.
With skills, Claude invokes functionality on its own: it reads the skill’s description and decides when it’s relevant. Claude is in control.
Skills come in two flavors:
- Personal (global): Stored in
~/.claude/skills/skill-name/, available across all projects - Project (local): Stored in
.claude/skills/skill-name/, version-controlled and shared with your team
Project skills are the interesting ones: they encode team workflows directly in the repo. Every developer—and every Claude instance—gets the same defaults.
The Token Efficiency Advantage
Skills are intentionally cheap to keep around.
When you add a skill, only its metadata loads initially:
name: "code-review"
description: "Analyzes code structure, checks for bugs, suggests improvements, and verifies adherence to project conventions"
That’s it. Two fields. Maybe ~30 tokens.
The rest of the skill—reference docs, examples, templates, scripts—loads only when Claude decides the skill is relevant. Lazy evaluation, but for AI capability.
The practical impact: you can define dozens of skills without sacrificing context for the work you’re doing right now. Conversation history, code excerpts, and the current task stay at the top of the scrollback. Skills wait off-screen until invoked.
Anatomy of a Skill
A well-structured skill looks like this:
my-skill/
├── SKILL.md # Required: metadata + core instructions
├── reference.md # Optional: detailed documentation
├── examples.md # Optional: usage examples
├── scripts/
│ └── helper.py # Optional: executable utilities
└── templates/
└── template.txt # Optional: output templates
The only required file is SKILL.md. It must include a metadata header:
---
name: "database-migration"
description: "Runs database migrations with verification and backup"
---
Followed by markdown instructions:
## Instructions
Run exactly this script, do not modify the command or add additional flags.
python scripts/migrate.py --verify --backup
Everything else is optional, but strategically useful:
- Reference files provide deep context when Claude needs it
- Examples show expected patterns
- Scripts ensure repeatability without code generation overhead
- Templates define output structure
Files can reference each other, but keep the graph shallow. Reference files should link directly from SKILL.md, not create multi-level chains. When Claude loads a skill, you want it to read complete files—not chase fragments across a dependency maze.
For reference files longer than 100 lines, include a table of contents at the top. Even when Claude previews with partial reads, it can see the full scope of available information.
Design Principles
Skills should follow the single responsibility principle, just like functions. If a skill can do many things, split it into multiple simple skills.
Bad: code-quality skill that reviews, formats, tests, and documents code
Good: Separate skills for code-review, format-code, run-tests, generate-docs
Why? Because Claude chooses skills based on their descriptions. A vague, multi-purpose skill is harder to match to intent than a focused one.
Context management still matters. Skills are token-efficient on load, but once loaded, they stay in context. Write concisely. Claude is smart—you don't need to over-explain simple instructions.
Controlling Model Freedom
Skills let you define the level of autonomy Claude has when performing a task. You can provide rough guidelines or exact instructions.
High freedom (Claude interprets and adapts):
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
Claude will approach each codebase differently, adapting to the language, conventions, and constraints.
Low freedom (Claude executes precisely):
## Database migration
Run exactly this script, do not modify the command or add additional flags.
python scripts/migrate.py --verify --backup
No interpretation. No variation. Just execution.
Choose based on the task. Creative work (writing, refactoring, design) benefits from freedom. Critical operations (migrations, deployments, security checks) benefit from constraints.
Practical Tips
Validate outputs. Tell Claude how to check its own work. For code changes, specify which tests or linters to run. For operational tasks, define success criteria. Self-validation saves round trips.
Use templates for structured output. If a skill generates files, provide a template. Claude won't have to guess at formatting—it'll fill in the blanks.
Offload repetition to scripts. If a skill does the same thing repeatedly (e.g., formatting API responses), write a script instead of generating code each time. No tokens for generation. No extra context load. Just execution.
Write in third person. Skill descriptions inject into Claude’s system prompt. Mixing POV (first-person in skills, third-person in system instructions) can confuse invocation. Prefer: “Analyzes code structure,” not “I analyze code structure.”
Be specific with triggers. Include both what the skill does and when to use it. "Generates SQL migration files when the user requests database schema changes" is clearer than "Handles database migrations."
When to Use Skills vs. MCP
Skills aren't a replacement for MCP servers—they're complementary.
Use MCP when you need:
- Real-time external data (databases, APIs, file systems)
- Stateful interactions (maintaining connections, sessions)
- System-level operations (running servers, managing processes)
Use skills when you need:
- Workflow definitions (how to review PRs, write docs, structure tests)
- Team conventions (code style, commit formats, naming patterns)
- Procedural knowledge (deployment steps, debugging checklists)
The line is simple: MCP servers do things in the world. Skills teach Claude how to approach things.
Define Your Own Workflow
The real power of skills is that they let you encode your working relationship with Claude. Not just “what can Claude do,” but “how does Claude work with us here?”
A skill for code review can define your team's standards. A skill for writing documentation can enforce your preferred structure. A skill for debugging can follow your diagnostic process.
It’s lightweight enough to start with a single SKILL.md, but strong enough to guide complex, multi-step work. You get much of the control you want—without paying the always-loaded context cost.
And because project skills live in your repository, they evolve with your codebase. When your team changes a convention, you update the skill. Everyone—humans and Claude instances alike—stays in sync.
That's the advantage: not just extending what Claude can do, but shaping how it does it.