How to Create a Claude Skill
A strong Claude Skill begins with one repeatable job and instructions that teach a reliable procedure. Start small, test it on real work, then add supporting resources only when they improve reliability.
Quick answer
Create .claude/skills/<skill-name>/SKILL.md, write a useful description, add concise workflow instructions, optionally add scripts or references, then test the skill by invoking /<skill-name> or asking Claude for a task that matches the description.
1. Define one repeatable job
Avoid a skill that tries to be an entire department. Narrow scope makes triggering, testing and maintenance easier.
2. Write useful metadata
Description should explain what the skill does and when it should apply. Name is optional for normal project skills because the directory name supplies the command name.
3. Encode the workflow
Write the successful procedure, constraints, validation checks and important failure modes. Prefer direct actions over long explanations.
4. Add resources progressively
Keep SKILL.md focused. Place large references, examples or deterministic scripts beside it and reference them when Claude should load or run them.
5. Test and revise
Test the skill on realistic tasks. When Claude goes off track, update the instruction that caused the failure rather than adding speculative rules.
Starter project skill structure
.claude/skills/release-check/
├── SKILL.md
├── references/
│ └── checklist.md
└── scripts/
└── validate.shOfficial Claude documentation
Claude Code changes quickly. Use Anthropic’s documentation as the source of truth for current configuration fields and behavior.
Open Anthropic docs →Related Claude tools and guides
Frequently asked questions
Where do project skills live?
Under .claude/skills/<skill-name>/SKILL.md.
Should every Skill include scripts?
No. Add scripts only when deterministic execution or validation materially improves the workflow.
How do I invoke a skill manually?
For a normal project skill, the directory name becomes the slash command, such as /release-check.