Claude Skills are file-based extensions that teach Claude how to do specific tasks. Each skill is a self-contained directory with a SKILL.md file describing what it does and how to do it.
This page covers the architecture and the patterns for designing skills.
A skill lives in a directory:
my-skill/
├── SKILL.md (required: name, description, instructions)
├── scripts/ (optional: executable helpers)
├── templates/ (optional: file templates)
├── references/ (optional: detailed reference material)
└── examples/ (optional: worked examples)
The SKILL.md frontmatter:
---
name: my-skill
description: Brief description for Claude to decide when to invoke
---
Description is critical — Claude reads it to decide whether to invoke the skill. Specific descriptions invoke when relevant; vague descriptions don't.
When a user asks Claude to do something:
Skill toolThe skill author's job: write instructions that produce reliable behavior.
Bad: "helps with development" Good: "creates Java records with proper validation, builders, and equals/hashCode for domain types"
The description filters when Claude invokes. Specific = invoked at the right time.
TRIGGER when: user asks for X, code uses pattern Y
SKIP: file is .test, language is Python
Explicit triggers help Claude pick the right skill.
Bad: "follow best practices" Good: "use parameterized queries; validate input at the boundary; emit structured logs"
Specific instructions produce specific behavior.
Worked input/output examples are dramatically more useful than abstract descriptions. Real example > paragraph of description.
A skill should do one thing. Multiple skills compose for complex tasks. See SkillComposition.
For information Claude doesn't need every time, put it in references/. Skill instructions can say "see references/api-spec.md for details" — Claude reads when needed.
This keeps SKILL.md short while having depth available.
Some operations are better as code than instructions. Skills can include scripts:
Run this script: `./scripts/format-output.sh`
Claude executes; scripts encapsulate logic that's awkward in natural language.
For generating files: provide templates. Claude fills them in.
Complex skills may have multiple instruction files. SKILL.md is the entry point; other files provide depth.
What does Claude do repeatedly that would benefit from systematization? Common needs: code review style, file conventions, deployment steps.
Write SKILL.md with clear description, instructions, examples.
Try the skill in conversations. Does Claude invoke it at the right times? Does it produce expected results?
Skills evolve. Real-world usage exposes gaps; refine.
When the skill is stable, document it for other users. See SkillDocumentation.
Some skills define multi-step workflows:
1. First, do A
2. Then, do B
3. Finally, do C
Claude follows step by step. Useful for procedures with required ordering.
If situation X: do A
If situation Y: do B
Otherwise: do C
Encodes branching logic.
Before starting:
- Verify the file exists
- Check the user's permissions
Ensures the skill operates on valid state.
After completing:
- Verify the build passes
- Confirm tests added
Verification before declaring success.
The instructions are read; not executed. Subtle requirements (timing, side effects) are hard to express in markdown.
For complex logic, scripts (executed by the skill) are more reliable than long markdown instructions.
Multiple skills may match a task. Claude picks one. Disambiguation via specific descriptions.
Each conversation loads them fresh. Skill changes affect future conversations, not running ones.