Design effective Claude Code skills with optimal descriptions, progressive disclosure, and error prevention patterns. Covers freedom levels, token efficiency, and quality standards. Use when: creating new skills, improving skill descriptions, optimizing token usage, structuring skill content, or debugging why skills aren't being discovered.
Status: Production Ready Last Updated: 2026-01-09 Dependencies: None Reference: Anthropic's skill-creator
To scaffold a new skill, use the /create-skill command:
/create-skill my-new-skill
To design an effective skill, continue reading this guide.
Every token in your skill competes with conversation context. Be ruthlessly concise.
Ask for each paragraph:
references/ instead of main SKILL.md?Load information in layers:
| Layer | When Loaded | Target Size | Content |
|---|---|---|---|
| Metadata | Always | 40-55 tokens | name + description |
| SKILL.md | When triggered | <5k words | Instructions, patterns |
| Resources | As needed | Variable | scripts/, references/, assets/ |
Match instruction specificity to error probability:
High Freedom (text instructions)
Medium Freedom (pseudocode/patterns)
[CUSTOMIZE] placeholdersLow Freedom (specific scripts/templates)
The description is the most critical part - it determines if your skill gets discovered.
# Too short (loses context):