majiayu000 Skill Creation
Create well-structured skills using progressive disclosure and project conventions.
Reference: best-practices.md for comprehensive guidance, reference.md for project patterns and frontmatter specs.
Workflow
Step 1: Understand Use Cases
Gather concrete examples of how the skill will be used:
- What tasks will it handle?
- What would users say to trigger it?
- What variations exist?
Skip this step only when usage patterns are already clearly understood.
Step 2: Plan Contents
Analyze each use case to identify reusable resources:
| Resource Type | When to Use | Example |
|---|---|---|
scripts/ |
Same code rewritten repeatedly | rotate_pdf.py |
references/ |
Domain knowledge Claude needs | schema.md, api.md |
assets/ |
Files used in output | template.html, logo.png |
templates/ |
Document structure patterns | report.md |
Step 3: Choose Frontmatter
Required fields:
name: skill-name # Lowercase, hyphens, max 64 chars
description: | # Max 1024 chars
[What it does]. Use when [context].
Optional fields:
| Field | Purpose | Example |
|---|---|---|
context |
Run in forked sub-agent | context: fork |
agent |
Specify agent type | agent: haiku |
user-invocable |
Hide from slash menu | user-invocable: false |
allowed-tools |
Restrict available tools | See reference.md |
hooks |
Lifecycle hooks (PreToolUse, PostToolUse, Stop) | See reference.md |
Naming pattern: <namespace>[-<subnamespace>]-<action>
code-debug,spec-create,git-worktree-use
Description format: Third person, what + when.
- "Generate GitHub issue drafts from spec directories. Use when converting specs to GitHub issues."
Step 4: Create Structure
mkdir -p .claude/skills/{skill-name}
Standard structure:
.claude/skills/{skill-name}/
├── SKILL.md # Main instructions (<500 lines)
├── templates/ # Document templates (.md)
├── scripts/ # Executable code (.sh, .py)
└── references/ # Extended documentation
Step 5: Implement & Test
Write SKILL.md:
- Keep under 200 lines (500 max)
- Progressive disclosure: SKILL.md → references/
- Include concrete examples, no emojis
- Reference authoritative docs (don't duplicate)
Test with real tasks:
- Does the description trigger correctly?
- Can Claude find bundled resources?
- Does the workflow complete successfully?
Degrees of Freedom
Match specificity to task fragility:
High freedom - Multiple approaches valid, context-dependent:
## Code review
1. Analyze structure and organization
2. Check for bugs and edge cases
3. Suggest improvements
Low freedom - Operations fragile, consistency critical:
## Database migration
Run exactly: `python scripts/migrate.py --verify --backup`
Do not modify flags.
Skill Types
| Type | Characteristics | Examples |
|---|---|---|
| Operational | Multi-step workflow, state changes, document templates | spec-create, spec-archive |
| Generation | Transform input → structured output, format templates | spec-issues-create |
| Guidance | Imperative instructions, code patterns | code-implement, code-debug |
Success Criteria
- Name follows
<namespace>[-<subnamespace>]-<action> - Description is third person with what + when
- SKILL.md under 200 lines (500 max)
- Workflow steps numbered and actionable
- Templates extracted to separate files
- References point to authoritative sources
- No emojis (text markers only)
Reference
- best-practices.md - Core principles, patterns, checklist
- reference.md - Project patterns, frontmatter specs, anti-patterns