Skill Creator Skill | Agent Skills

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, hyphens
[ ] description: starts with "Use when...", includes ALL triggers
[ ] keywords: 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 |

Agent Skills: Skill Creator

Skill Files