| name | create-skill |
| description | Creates or modifies agent skills, including single-workflow and multi-workflow (orchestrator) skills. Use when the user wants to create, write, author, scaffold, edit, update, fix, or refactor a skill, or migrate a skill from single to multi-workflow. |
Step 1: Gather context
Ask the user what the skill should do, when it should activate, and any conventions it should follow.
Step 2: Write the frontmatter
Only name and description loaded at startup — agent decides whether to load the skill based on description alone.
---
name: kebab-case-name
description: [What it does, third person]. Use when [activation triggers].
---
Description rules
- Third person always — "Generates X", never "I help" or "You can use"
- First sentence = capability, second = "Use when [triggers]"
- Include synonyms and colloquial phrasing to maximize activation surface
- Optionally add "Do not use for [X]" to reduce false positives
- <200 chars ideal, 1024 max
description: Generates conventional commit messages from staged changes. Use when committing code, writing commit messages, or preparing a release.
description: Helps with git stuff.
description: I can help you write commit messages.
Step 3: Write the body
Sacrifice grammar for concision and scannability. Every line must justify its token cost — only include what the agent doesn't already know.
Principles
- Freedom matching — prescriptive for fragile ops, flexible for open-ended tasks
- Examples over rules — concrete input/output pairs teach better than abstract descriptions
- No over-explaining — the agent knows what PDFs are, how imports work, etc.
Format
## headings for steps or sections- Procedural skills:
## Step N: [Action]
- Reference skills:
## Quick Start → ## Patterns → ## Advanced
- Before/after examples for transformations
- Tables for quick-reference lookups
- Checklists for complex multi-step workflows
- Always end with
## Acceptance checklist — agent verifies all steps completed before finishing
- Consistent terminology — one term per concept
- No time-sensitive info
- Reference paths as inline code:
references/foo.md, never markdown links
See examples/ for complete skill examples by type:
| Example | When to use |
|---|
examples/minimal.md | Simple single-file skill, no folders |
examples/procedural.md | Defined steps, defined outputs |
examples/open-ended-with-examples.md | Output varies by use case |
examples/with-scripts.md | Deterministic operations |
examples/with-references.md | Conditional/alternate flows |
examples/reference-style.md | Knowledge base, no steps |
examples/combined.md | Scripts + examples + references |
Step 4: Organize the directory
Single-workflow vs multi-workflow skills
Most skills are single-workflow — one SKILL.md covers one concern. Use this by default.
A multi-workflow skill is needed when a single domain has multiple distinct procedures that share a description trigger. SKILL.md becomes a router that dispatches to internal flows based on the task. Each flow is a self-contained mini-skill inside flows/.
Use multi-workflow when:
- The domain has 3+ distinct procedures (e.g., setup, create route, data fetching)
- Procedures are independent — running one doesn't require another
- A single description can't cover all procedures without being vague
Migrate from single to multi when:
- SKILL.md exceeds 200 lines even after splitting into references
- The skill covers multiple unrelated procedures under one domain
Keep the description in sync — when flows are added, modified, or removed, update SKILL.md's description to reflect current capabilities.
For full structure and conventions, see references/orchestrator.md.
Single-workflow structure
skill-name/
├── SKILL.md # Required — <200 lines
├── scripts/ # Optional — deterministic executable code
│ └── setup.ts
├── examples/ # Optional — sample output per use case
│ ├── bug-fix.md
│ └── refactor.md
└── references/ # Optional — conditional flows, on-demand
└── advanced.md
scripts/
Deterministic, repeatable operations (validation, scaffolding, setup). Executed, not read — code never enters context, only output.
- Run with
bun: bun scripts/setup.ts
- Name by function:
validate_form.ts, scaffold.ts
- Handle errors explicitly — never delegate to agent
examples/
Sample files for open-ended output not fully defined in SKILL.md. One file per use case.
- NOT needed for closed procedures where output is specified in steps
- Reference: "See
examples/ for sample outputs"
references/
Conditional flows, alternate paths, domain knowledge not always needed. Loaded on-demand — zero tokens until needed.
- One level deep — never reference a reference
- TOC for files >100 lines
Acceptance checklist
