write-a-skill

Writing Skills

Process

1. 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

2. 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

3. 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

4. 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.md must live inside the skill directory
• Frontmatter name must 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-tools in 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)