write-a-skill
Create new agent skills with clear triggers, compact instructions, and optional bundled references or helper scripts. Use when user wants to create, write, design, refine, or package a reusable skill.
SKILL.mdskills/writing/write-a-skill/SKILL.md
GitHubWriting Skills
Process
Gather requirements
- Task/domain covered
- Concrete triggers and example requests
- Output shape: instructions only vs helper scripts/resources
- Target scope: personal, project-local, or shareable
- Any reference material, conventions, or constraints
Design the skill shape
- Keep the main path short
- Put rare/advanced material in linked files
- Add scripts only for deterministic or repetitive work
- Prefer one reusable skill over many overlapping ones
Draft the skill package
- Create
SKILL.md - Add
REFERENCE.md,EXAMPLES.md, or templates only if they reduce clutter - Keep assets beside the skill that uses them
- Create
Review with the user
- Does it trigger on the right requests?
- Is the default workflow clear?
- Anything ambiguous, missing, or too verbose?
- Should it stay broad or be split into multiple skills?
Skill Structure
skill-name/
├── SKILL.md # Main instructions (required)
├── REFERENCE.md # Detailed docs (optional)
├── EXAMPLES.md # Example prompts/flows (optional)
├── templates/ # Template files (optional)
└── scripts/ # Helper scripts (optional)
└── helper.js
Rules:
SKILL.mdmust live inside the skill directory- Frontmatter
namemust match the skill directory name exactly - Nested category folders are fine; the immediate parent directory is the skill name
- If tool restrictions matter, add
allowed-toolsin frontmatter
Example:
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
allowed-tools: read bash write
---
SKILL.md Template
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---
# Skill Name
## Quick start
[Minimal working path]
## Workflow
[Ordered steps for the common case]
## Edge cases
[Constraints, gotchas, escalation rules]
## References
See [REFERENCE.md](REFERENCE.md)
Description Requirements
The description is the routing signal used to decide whether to load the skill. Write it so the runtime can distinguish this skill from nearby ones.
Include:
- What capability it provides
- When to trigger it
- Concrete keywords, contexts, domains, or file types
Format:
- Keep it short and specific
- Write in third person / neutral imperative
- First clause: what it does
- Second clause:
Use when ...
Good:
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
Bad:
Helps with documents.
When to Add Scripts
Add helper scripts when:
- The operation is deterministic
- The same code would otherwise be regenerated often
- Validation or formatting should be exact
- Failure modes need explicit handling
Do not add scripts for one-off reasoning.
When to Split Files
Split into linked files when:
SKILL.mdis getting crowded- Some content is rare or advanced
- Examples/templates would distract from the common path
- Reference material changes independently from the main workflow
Keep references shallow and intentional.
Review Checklist
After drafting, verify:
- Description clearly says
Use when ... -
namematches directory name - Default workflow easy to follow
- No platform-specific assumptions unless intentional
- No stale or time-sensitive claims
- Examples/triggers concrete
- References only added when they reduce clutter
- Tool access narrowed when useful
Communication
Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.