Meta-Skill Guide: Creating Claude Code Custom Skills
Quick Reference
| Aspect |
Constraint |
Recommendation |
| SKILL.md size |
No hard limit |
Keep under 500 lines |
| Skill name |
Max 64 chars |
Lowercase, hyphens, gerund form (processing-pdfs) |
| Description |
Max 1024 chars |
WHAT it does + WHEN to use (third person) |
| Reference depth |
One level deep |
SKILL.md -> File.md only |
| File paths |
Forward slashes |
Always scripts/helper.py |
| Subagent context |
Completely isolated |
NO conversation history, NO memory |
Architecture: Three-Level Progressive Loading
Level 1: Metadata (~100 tokens/skill)
---
name: skill-name
description: Brief description with usage triggers
---
- Loaded at Claude Code startup
- Critical for skill discovery
Level 2: Instructions (<5,000 tokens)
- Main SKILL.md body content
- Loaded when user request matches description
- Optimal: Under 500 lines
Level 3: Resources (Unlimited)
- Additional markdown files, scripts, templates
- Loaded as needed via bash navigation
- Scripts execute without loading code into context
File Structure
skill-name/
├── SKILL.md # Main instructions (mandatory)
├── reference/ # Additional documentation
│ ├── advanced.md
│ └── api_reference.md
├── scripts/ # Executable code
│ └── validator.py
└── templates/ # Templates
└── template.ext
YAML Frontmatter
Required:
---
name: skill-name
description: What skill does and when to use it. Include triggers and key terms.
---
Optional (Claude Code):
allowed-tools: ["Bash", "Read", "Write", "Edit"]
model: claude-sonnet-4-5-20250929
Naming Rules:
- Max 64 chars, lowercase letters/numbers/hyphens
- Use gerund form:
processing-pdfs (not process-pdf)
- Avoid vague names:
helper, utils, documents
Skill Levels
| Level |
Lines |
Characteristics |
Template |
| Simple |
100-300 |
Single task, no scripts |
reference/templates/simple.md |
| Moderate |
300-500 |
Multiple ops, validation scripts |
reference/templates/moderate.md |
| Advanced |
500+ distributed |
Multi-phase, extensive refs |
reference/templates/advanced.md |
Best Practices Summary
Top 10 DOs
- Keep SKILL.md under 500 lines
- Write descriptions in third person with triggers
- Use consistent terminology throughout
- Provide concrete examples with input/output pairs
- Implement validation loops (Create -> Validate -> Fix)
- Structure long files with table of contents
- Use checklists for complex tasks
- Solve problems in scripts, don't punt to Claude
- Justify all constants and magic numbers
- List required packages explicitly
Top 10 DON'Ts
- Reference time-sensitive information
- Use Windows-style paths (
scripts\helper.py)
- Assume tools are pre-installed
- Use vague MCP tool references
- Provide too many equal options (decision paralysis)
- Create deeply nested references (one level max)
- Skip validation for quality tasks
- Mix inconsistent terminology
- Leave constants unexplained
- Assume subagent context from conversation
Full checklist: reference/best-practices.md
Subagent Integration Summary
When to Delegate
| Task Type |
Recommendation |
| Simple, <10 min |
Direct in skill |
| Research-heavy |
Delegate to context-collector |
| Multi-stage |
Orchestrate specialists |
| Language-specific |
Language expert subagents |
| Quality assurance |
code-reviewer, test-automator |
Key Constraints
- NO conversation history access - each invocation is fresh
- NO nested delegation - main agent orchestrates all
- File artifacts for state transfer - save results to files
- Explicit output format - prevent context overload
Orchestration Patterns
- Parallel - Independent tasks, single message, multiple Task calls
- Sequential - Dependent tasks, file artifacts between steps
- Hub-and-Spoke - Implementation + multiple reviewers
- Iterative - Architect -> Reviewer cycles
Full guide: reference/subagent-patterns.md
Domain Patterns Summary
| Domain |
Key Pattern |
Example |
| Creative |
Philosophy-first, reductive mastery |
algorithmic-art |
| Document |
Validation loops, zero-error mandate |
xlsx, pdf |
| Development |
Phase-based workflow, quality gates |
mcp-builder |
| Enterprise |
Template routing, clarification protocols |
internal-comms |
| Workflow |
Slash commands, automation |
worktree-manager |
Full patterns: reference/domain-patterns.md
Quality & Testing Summary
Build Evaluations First
- Run Claude WITHOUT skill on real tasks
- Create 3+ test scenarios
- Write minimal instructions to pass
- Iterate based on real behavior
Two-Claude Method
- Claude A: Skill author
- Claude B: Skill tester
- Iterate based on where B struggles
Cross-Model Testing
Full guide: reference/evaluation.md
Key Takeaways
Architecture
- Three-level progressive loading: metadata -> instructions -> resources
- Filesystem-based: bash navigation, scripts execute without loading
- One level deep references only
Structure
- SKILL.md under 500 lines
- YAML: name (64 chars) + description (1024 chars, third person)
- Forward slashes always, gerund naming
Subagents
- Context isolation: NO history, NO memory
- Main agent orchestrates all delegation
- File artifacts for state transfer
- 90% improvement with parallel specialists
Distribution
- Skills don't sync across surfaces
- Claude Code:
~/.claude/skills/ or .claude/skills/
- Share via git for teams
External References
Official Docs:
GitHub Examples:
Full links: reference/links.md
Version
v1.2.0 (December 2025) - Refactored to progressive disclosure pattern
1---2name: meta-skill-guide3description: Comprehensive guide for creating Claude Code custom skills. Use when asked to create, design, or improve custom skills for Claude Code. Provides templates, best practices, and patterns for simple, moderate, and advanced skills.4---5
6# Meta-Skill Guide: Creating Claude Code Custom Skills
7
8## Quick Reference
9
10| Aspect | Constraint | Recommendation |
11|--------|-----------|----------------|
12| **SKILL.md size** | No hard limit | Keep under 500 lines |
13| **Skill name** | Max 64 chars | Lowercase, hyphens, gerund form (`processing-pdfs`) |
14| **Description** | Max 1024 chars | WHAT it does + WHEN to use (third person) |
15| **Reference depth** | One level deep | SKILL.md -> File.md only |
16| **File paths** | Forward slashes | Always `scripts/helper.py` |
17| **Subagent context** | Completely isolated | NO conversation history, NO memory |
18
19---
20
21## Architecture: Three-Level Progressive Loading
22
23**Level 1: Metadata (~100 tokens/skill)**
24```yaml
25---
26name: skill-name
27description: Brief description with usage triggers
28---
29```
30- Loaded at Claude Code startup
31- Critical for skill discovery
32
33**Level 2: Instructions (<5,000 tokens)**
34- Main SKILL.md body content
35- Loaded when user request matches description
36- Optimal: Under 500 lines
37
38**Level 3: Resources (Unlimited)**
39- Additional markdown files, scripts, templates
40- Loaded as needed via bash navigation
41- Scripts execute without loading code into context
42
43---
44
45## File Structure
46
47```
48skill-name/
49├── SKILL.md # Main instructions (mandatory)
50├── reference/ # Additional documentation
51│ ├── advanced.md
52│ └── api_reference.md
53├── scripts/ # Executable code
54│ └── validator.py
55└── templates/ # Templates
56 └── template.ext
57```
58
59---
60
61## YAML Frontmatter
62
63**Required:**
64```yaml
65---
66name: skill-name
67description: What skill does and when to use it. Include triggers and key terms.
68---
69```
70
71**Optional (Claude Code):**
72```yaml
73allowed-tools: ["Bash", "Read", "Write", "Edit"]
74model: claude-sonnet-4-5-20250929
75```
76
77**Naming Rules:**
78- Max 64 chars, lowercase letters/numbers/hyphens
79- Use gerund form: `processing-pdfs` (not `process-pdf`)
80- Avoid vague names: `helper`, `utils`, `documents`
81
82---
83
84## Skill Levels
85
86| Level | Lines | Characteristics | Template |
87|-------|-------|-----------------|----------|
88| **Simple** | 100-300 | Single task, no scripts | [reference/templates/simple.md](reference/templates/simple.md) |
89| **Moderate** | 300-500 | Multiple ops, validation scripts | [reference/templates/moderate.md](reference/templates/moderate.md) |
90| **Advanced** | 500+ distributed | Multi-phase, extensive refs | [reference/templates/advanced.md](reference/templates/advanced.md) |
91
92---
93
94## Best Practices Summary
95
96### Top 10 DOs
971. Keep SKILL.md under 500 lines
982. Write descriptions in third person with triggers
993. Use consistent terminology throughout
1004. Provide concrete examples with input/output pairs
1015. Implement validation loops (Create -> Validate -> Fix)
1026. Structure long files with table of contents
1037. Use checklists for complex tasks
1048. Solve problems in scripts, don't punt to Claude
1059. Justify all constants and magic numbers
10610. List required packages explicitly
107
108### Top 10 DON'Ts
1091. Reference time-sensitive information
1102. Use Windows-style paths (`scripts\helper.py`)
1113. Assume tools are pre-installed
1124. Use vague MCP tool references
1135. Provide too many equal options (decision paralysis)
1146. Create deeply nested references (one level max)
1157. Skip validation for quality tasks
1168. Mix inconsistent terminology
1179. Leave constants unexplained
11810. Assume subagent context from conversation
119
120**Full checklist:** [reference/best-practices.md](reference/best-practices.md)
121
122---
123
124## Subagent Integration Summary
125
126### When to Delegate
127
128| Task Type | Recommendation |
129|-----------|----------------|
130| Simple, <10 min | Direct in skill |
131| Research-heavy | Delegate to `context-collector` |
132| Multi-stage | Orchestrate specialists |
133| Language-specific | Language expert subagents |
134| Quality assurance | `code-reviewer`, `test-automator` |
135
136### Key Constraints
137- **NO conversation history access** - each invocation is fresh
138- **NO nested delegation** - main agent orchestrates all
139- **File artifacts for state transfer** - save results to files
140- **Explicit output format** - prevent context overload
141
142### Orchestration Patterns
1431. **Parallel** - Independent tasks, single message, multiple Task calls
1442. **Sequential** - Dependent tasks, file artifacts between steps
1453. **Hub-and-Spoke** - Implementation + multiple reviewers
1464. **Iterative** - Architect -> Reviewer cycles
147
148**Full guide:** [reference/subagent-patterns.md](reference/subagent-patterns.md)
149
150---
151
152## Domain Patterns Summary
153
154| Domain | Key Pattern | Example |
155|--------|-------------|---------|
156| **Creative** | Philosophy-first, reductive mastery | `algorithmic-art` |
157| **Document** | Validation loops, zero-error mandate | `xlsx`, `pdf` |
158| **Development** | Phase-based workflow, quality gates | `mcp-builder` |
159| **Enterprise** | Template routing, clarification protocols | `internal-comms` |
160| **Workflow** | Slash commands, automation | `worktree-manager` |
161
162**Full patterns:** [reference/domain-patterns.md](reference/domain-patterns.md)
163
164---
165
166## Quality & Testing Summary
167
168### Build Evaluations First
1691. Run Claude WITHOUT skill on real tasks
1702. Create 3+ test scenarios
1713. Write minimal instructions to pass
1724. Iterate based on real behavior
173
174### Two-Claude Method
175- **Claude A**: Skill author
176- **Claude B**: Skill tester
177- Iterate based on where B struggles
178
179### Cross-Model Testing
180- [ ] Haiku (cost optimization)
181- [ ] Sonnet (standard)
182- [ ] Opus (complex tasks)
183
184**Full guide:** [reference/evaluation.md](reference/evaluation.md)
185
186---
187
188## Key Takeaways
189
190### Architecture
191- Three-level progressive loading: metadata -> instructions -> resources
192- Filesystem-based: bash navigation, scripts execute without loading
193- One level deep references only
194
195### Structure
196- SKILL.md under 500 lines
197- YAML: name (64 chars) + description (1024 chars, third person)
198- Forward slashes always, gerund naming
199
200### Subagents
201- Context isolation: NO history, NO memory
202- Main agent orchestrates all delegation
203- File artifacts for state transfer
204- 90% improvement with parallel specialists
205
206### Distribution
207- Skills don't sync across surfaces
208- Claude Code: `~/.claude/skills/` or `.claude/skills/`
209- Share via git for teams
210
211---
212
213## External References
214
215**Official Docs:**
216- Skills Overview: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
217- Best Practices: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices
218- Claude Code Skills: https://docs.claude.com/en/docs/claude-code/skills
219
220**GitHub Examples:**
221- Anthropic Skills: https://github.com/anthropics/skills
222- Claude Cookbooks: https://github.com/anthropics/claude-cookbooks/tree/main/skills
223
224**Full links:** [reference/links.md](reference/links.md)
225
226---
227
228## Version
229
230**v1.2.0** (December 2025) - Refactored to progressive disclosure pattern
majiayu000