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

Good

description: Generates conventional commit messages from staged changes. Use when committing code, writing commit messages, or preparing a release.

Bad — vague

description: Helps with git stuff.

Bad — first person

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

• Description: third person, specific, activation triggers

• Only info the agent doesn't already know

• Concise, scannable, no unnecessary prose

• Concrete examples, consistent terminology

• No time-sensitive info

• <200 lines or split into references/examples

• scripts/ run with bun , handle errors

• examples/ only for open-ended output

• references/ only for conditional flows

• Paths as inline code, no markdown links

• Ends with ## Acceptance checklist

• Multi-workflow: description reflects all current flows