About Skills
Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.
What Skills Provide
- •Specialized workflows - Multi-step procedures for specific domains
- •Tool integrations - Instructions for working with specific file formats or APIs
- •Domain expertise - Company-specific knowledge, schemas, business logic
- •Bundled resources - Scripts, references, and assets for complex tasks
When to use
- •"Build me a new skill for X"
- •"Create a skill that does Y"
- •"Validate my skill structure"
- •"Improve this existing skill"
- •"What sections should a skill have?"
When NOT to use
- •General coding tasks (use other skills or direct Claude)
- •Questions about Claude Code itself (use claude-code-guide)
- •Simple file operations that don't need a skill workflow
Core Principles
Concise is Key
The context window is a public good. Challenge each piece of information: "Does Claude really need this?" Prefer concise examples over verbose explanations.
Degrees of Freedom
Match specificity to task fragility:
| Level | Use When |
|---|---|
| High freedom | Multiple valid approaches, context-dependent decisions |
| Medium freedom | Preferred pattern exists, some variation acceptable |
| Low freedom | Fragile operations, consistency critical |
Think of Claude exploring a path: a narrow bridge needs guardrails (low freedom), an open field allows many routes (high freedom).
Anatomy of a Skill
code
skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name + description) │ └── Markdown instructions ├── scripts/ - Executable code (Python/Bash) ├── references/ - Documentation loaded as needed └── assets/ - Templates, binaries for output
SKILL.md Frontmatter
Only two required fields:
- •
name: The skill identifier (lowercase, hyphens) - •`description**: Triggers + purpose. Include "Use this when..." with specific conditions.
Do not add license or other fields.
When to Use Each Resource Type
- •scripts/: Deterministic operations, repeatedly rewritten code
- •references/: Long docs, schemas, APIs, patterns Claude references
- •assets/: Templates, icons, boilerplate copied to output
Progressive Disclosure
Keep SKILL.md under 500 lines. Move details to references:
code
# Quick start [essential workflow] # Advanced - Feature A: See [REFERENCES/A.md](REFERENCES/A.md) - Feature B: See [REFERENCES/B.md](REFERENCES/B.md)
Skill Creation Workflow
Step 1 — Capture Requirements
See SKILLSPEC.md for the format.
Step 2 — Plan Resources
For each example, determine:
- •Does it need a script? (deterministic, repeated)
- •Does it need a reference? (long docs, schemas)
- •Does it need assets? (templates, boilerplate)
Step 3 — Initialize
bash
python "{baseDir}/scripts/init_skill.py" <skill-name> --path <output-dir>
Step 4 — Fill In
- •Replace generated SKILL.md with final version
- •Add scripts to
scripts/ - •Add docs to
references/ - •Add assets to
assets/ - •Delete unused sample files
Step 5 — Gap Analysis
Verify all sections exist:
| Section | Required |
|---|---|
| Description | States when to use |
| When to use | 3-8 triggers |
| When NOT to use | Recommended |
| Workflow | Numbered steps |
| Tool usage | Scripts + references documented |
| Failure handling | Explicit table/list |
| Examples | Concrete walkthroughs |
| Acceptance tests | 5+ test cases |
Use CHECKLIST.md for full validation.
Step 6 — Precision Analysis
Check trigger quality:
- •Overlap: Do triggers match other common skills?
- •Specificity: Are triggers specific enough?
- •Differentiation: Document distinctions if overlap exists
Step 7 — Validate
bash
python "{baseDir}/scripts/quick_validate.py" <skill-dir>
Updating Existing Skills
- •Run gap analysis against CHECKLIST.md
- •Run precision analysis on triggers
- •Apply fixes:
- •Improve description/triggers
- •Add missing failure handling
- •Add "When NOT to use"
- •Move long content to references/
- •Add scripts for repeated steps
- •Re-validate
Failure Modes
| Failure | Response |
|---|---|
Missing name or description | Validation fails; add required fields |
| Invalid skill name format | Use lowercase, 2-64 chars, a-z0-9_- |
| Placeholders (TODO) in SKILL.md | Replace with actual content before validating |
| {baseDir} reference not found | Verify path exists relative to skill folder |
| Validation errors | Fix all ERRORs before validating |
Examples
Creating a New Skill
User: "Build me a skill to rotate PDFs"
Assistant uses this workflow:
- •Captures requirements (rotate PDF, 3 triggers)
- •Plans resources (scripts/rotate_pdf.py)
- •Runs init_skill.py
- •Fills in SKILL.md with PDF-specific workflow
- •Adds rotate_pdf.py script
- •Validates
Updating an Existing Skill
User: "This skill is missing failure handling"
Assistant:
- •Runs gap analysis → finds missing "Failure handling"
- •Adds failure modes table
- •Re-validates
Acceptance Tests
| Prompt | Expected Behavior |
|---|---|
| "Build a new skill called pdf-editor" | Creates skill scaffold, runs init script |
| "Create a skill for image processing" | Follows full workflow, validates skill |
| "Validate my skill at /path/to/skill" | Runs quick_validate.py, reports issues |
| "What sections should a skill have?" | References checklist.md |
| "Help me improve my existing skill" | Runs gap analysis, suggests fixes |
| "Show me the skill spec format" | References skill_spec.md |
| "Why isn't my skill triggering?" | Checks trigger specificity, suggests improvements |