| name | create-skill |
| description | Create or improve a Claude Code skill (SKILL.md). Use when building a new skill, reviewing an existing skill for quality, or converting a repeated workflow into a reusable skill. |
Create or improve the skill: $ARGUMENTS
Philosophy
A skill sets the tone for a good completion — it doesn't teach Claude things it already knows. Every line must justify its token cost. If Claude would do it correctly without being told, cut it.
Research: LLM reasoning degrades at ~3,000 input tokens. A well-structured 16K prompt outperforms a monolithic 128K one. Recency bias causes early instructions to be undervalued. Conciseness isn't aesthetic — it's performance.
Before Writing
- Run the task without a skill first. Note where Claude fails or produces generic output. Those gaps — and only those — are what the skill should address.
- Identify 2-3 concrete use cases from real work, not hypothetical ones
- Write the description first. If you can't say when it applies in one sentence, it's too broad
- Decide invocation style: default (both),
disable-model-invocation: true (user-only, for side effects), or user-invocable: false (claude-only, for background knowledge)
Description
The description is everything. Claude routes to skills through pure language reasoning — no embeddings, no classifiers.
Measured activation rates by description quality:
| Description Quality | Activation Rate |
|---|
| Unoptimized | ~20% |
| Optimized | ~50% |
| With usage examples | 72-90% |
Rules:
-
Third person: "Generates migration files" not "I help you generate migrations"
-
Two parts: what it does + when to use it
-
Front-load the key use case — capped at 250 chars
-
Match the user's natural language, not formal abstractions
Good:
description: Generate architecture diagrams as .excalidraw files from codebase analysis. Use when the user asks to create architecture diagrams, system diagrams, visualize codebase structure, or describe flows visually.
Bad:
description: Helps with diagrams
Content: Show, Don't Lecture
Examples beat rules. One input/output pair communicates more per token than a paragraph of prose. Examples should outweigh rules in the skill.
Bad (~150 tokens, teaches Claude what it already knows):
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use...
Good (~50 tokens, provides the non-obvious choice):
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
State intent and constraints, not implementation steps. "Return consistent error formats with status codes" beats "You must always check if the response object has a status field and if it does then..."
Use positive framing. "Use named exports exclusively" over "Do NOT use default exports." Models process affirmative statements more reliably.
State what the skill doesn't do — this prevents inappropriate activation and scope creep.
Calibrate Freedom Per Step
Not every step in a skill needs the same level of prescription. Match constraint strength to the step's fragility:
| Freedom | When | Example |
|---|
| Low — exact command, no variation | Fragile, error-prone, consistency critical | python scripts/migrate.py --verify --backup |
| Medium — pattern with parameters | Preferred approach exists, some variation ok | "Use this template, customize as needed" |
| High — text guidelines | Multiple valid approaches, context-dependent | "Review for bugs, edge cases, readability" |
Skills drift when steps lack quality criteria, not when they lack procedural detail. For judgment-dependent steps, specify the evaluation axes: "Evaluate cost, integration ease, and learning curve; recommend highest scorer" — not "Recommend the optimal tool."
Structure
Keep SKILL.md under 500 lines. Move detailed reference material to references/ — Claude loads it on demand. Reference files should be one level deep from SKILL.md (no chains).
skill-name/
├── SKILL.md # Core instructions
├── references/ # Loaded on demand
│ └── examples.md
└── scripts/ # Executed, not loaded into context
└── validate.sh
Checklist
