Skill Creator
Create modular, token-efficient skills that extend Claude's capabilities.
Critical: Description = Trigger
The description field in frontmatter is how Claude decides when to load a skill.
| Location | Claude Sees | Timing |
|---|---|---|
description (frontmatter) | Always in context | Before trigger |
| "When to Use" (body) | Only after triggered | Too late! |
Pattern:
---
name: pdf-toolkit
# GOOD - trigger info in description
description: "Use when processing PDFs, extracting forms, merging documents, or filling PDF forms. Load for any PDF manipulation task."
keywords: pdf, extract, merge, forms
---Anti-pattern:
---
name: pdf-toolkit
# BAD - trigger info only in body (Claude can't see until AFTER trigger)
description: "PDF manipulation toolkit"
---
## When to Use ← Claude never sees this before deciding to trigger!Skill Anatomy
skill-name/
├── SKILL.md (required) # Workflow + metadata (<5k words)
├── scripts/ (optional) # Executable code (0 tokens when run)
├── references/ (optional) # Docs loaded as needed
└── assets/ (optional) # Output resources (never loaded)Resource Types
| Type | When to Use | Token Cost | Examples |
|---|---|---|---|
| scripts/ | Repeated code, deterministic | 0 (executes) | rotate_pdf.py, validate.sh |
| references/ | Schemas, APIs, patterns | On-demand | schema.md, api_docs.md |
| assets/ | Templates, images | 0 (output only) | logo.png, template.docx |
Key insight: Scripts execute WITHOUT loading into context = 0 tokens.
Progressive Disclosure (3 Levels)
| Level | What | When Loaded | Token Budget |
|---|---|---|---|
| 1. Metadata | name + description | Always | ~100 words |
| 2. SKILL.md body | Instructions | On trigger | <5k words |
| 3. Resources | scripts/references/assets | As needed | Unlimited |
Result: 98% token savings vs loading everything upfront.
Skill Creation Workflow
1. Gather Examples
Ask user:
- What functionality should the skill support?
- Example usage scenarios?
- What triggers this skill?
2. Plan Resources
| Question | Maps To |
|---|---|
| What code gets rewritten? | scripts/ |
| What schemas get rediscovered? | references/ |
| What boilerplate gets recreated? | assets/ |
3. Initialize
scripts/init_skill.py <skill-name> --path <output-directory>4. Write SKILL.md
Order:
- Write description (with ALL trigger scenarios)
- Add keywords
- Write concise body (<5k words)
- Reference bundled resources
Frontmatter checklist:
name: lowercase, hyphensdescription: starts with "Use when...", includes ALL triggerskeywords: discovery tags
Body checklist:
- Instructions (imperative form)
- Resource table (what to load when)
- Quick reference (common commands)
5. Validate & Package
scripts/quick_validate.py <path/to/skill>
scripts/package_skill.py <path/to/skill> [output-dir]6. Iterate
Test on real tasks → identify gaps → update → test again.
Key Rules
| Rule | Why |
|---|---|
| Description = trigger | Claude decides from metadata, not body |
| Scripts = 0 tokens | Execute without loading into context |
| Tables over prose | 30-50% token savings |
| <5k words in SKILL.md | Move details to references/ |
| keywords for discovery | Helps Claude find relevant skills |
References
| File | Load When |
|---|---|
| references/best_practices.md | Writing style, organization |
| references/progressive_disclosure.md | Token efficiency patterns |
| references/examples.md | Skill structure examples |