Write a Skill

Process

1. Clarify scope -- ask the user (use AskUserQuestion when available; otherwise present as numbered options):
   • "What type of skill?" — Options: "Pure instructions (no scripts)", "Instructions + helper scripts", "Wrapper around CLI tool"
   • "Does it need pre-loaded context?" — Options: "Yes — auto-run commands on load (Recommended)", "No — gather context during workflow"
2. Explore existing skills -- ls the skills repo, read similar skills for conventions
3. Draft -- create SKILL.md
4. Review with user -- confirm coverage, ask what's missing

Structure

skill-name/
├── SKILL.md              # Required. All instructions live here.
└── scripts/              # Optional. Executable helpers only.
    └── scan-secrets.sh

Keep everything in SKILL.md. Only use scripts/ for executable files (.sh, .py) that are called via Bash.

SKILL.md Template

---
name: skill-name
description: One sentence what it does. Use when [triggers]. Don't use when [anti-triggers].
---

# Skill Name

## Workflow
[numbered steps]

## Rules
[hard constraints]

## Error Handling
[if X -- do Y]

Frontmatter Fields

Description Rules

The description is the only thing the agent sees when choosing which skill to load.

• Max 1024 chars
• First sentence: what it does
• Second sentence: Use when [triggers]
• Third sentence (optional): Don't use when [anti-triggers]

Good: Groups unstaged changes into atomic commits by concern. Use when user says "atomic commits" or wants to split changes before pushing. Bad: Helps with commits.

Examples

Minimal skill -- pure instructions, fits in ~20 lines:

---
name: grill-me
description: Interview the user relentlessly about a plan. Use when user says "grill me".
---

[instructions...]

Pre-loaded context -- ! prefix auto-runs commands on load:

## Pre-loaded context

- Status: !`git status`
- Diff: !`git diff HEAD`

Avoids wasting a turn fetching context the agent always needs.

Rules

• No time-sensitive info (versions, dates) in skills
• Include error handling for foreseeable failure modes
• Test the skill by invoking it before shipping

Anti-patterns

• Description without triggers: "Helps with testing." -- useless
• Hardcoded versions or dates that go stale
• No error handling for skills that run Bash commands