Skill File Structure

---
name: kebab-case-skill-name
description: One sentence saying WHEN to invoke this and what it does.
---

name

Kebab-case, verb-first. E.g. creating-feature-branch, reviewing-pull-request, debugging-flaky-test

description

Must answer "when should I invoke this?" — not just what it does. Include the trigger context.

## Context
When this skill applies and what problem it solves. 1–3 sentences maximum.
The agent reads this to confirm it has the right skill for the situation.

Length

1–3 sentences. Never a full paragraph.

Focus

Explain the why and when, not the how. The how is in Process.

## Process

1. **First step** — what to do and why.
2. **Second step** — specific action with enough detail to execute without guessing.
3. **Third step** — if a step has sub-steps, nest them:
   - Sub-step A
   - Sub-step B
4. **Final step** — what done looks like.

Numbering

Use numbered lists for ordered processes. Use bullet points for unordered options.

Detail level

Each step should be specific enough to execute without asking a follow-up question.

Headers

For complex processes, use sub-headings inside Process instead of a flat list.

## Checklist

- [ ] Step one complete
- [ ] Step two verified
- [ ] Step three done
- [ ] Final confirmation

When to include

Only when there are 5+ discrete, verifiable steps that must all be done and could be accidentally skipped.

When to omit

For narrative processes or anything with fewer than 5 steps — a checklist adds noise without value.

## Anti-Patterns

- **Never do X** — because it causes Y.
- **Avoid Z** — use W instead.

When to include

Only when there are well-known mistakes that are easy to make and costly to undo.

Format

Bold the bad thing. Explain the consequence in plain English.

## Examples

```bash
# Good: specific, actionable
git commit -m "feat(auth): add JWT refresh token rotation"

# Bad: vague
git commit -m "fix stuff"
```

When to include

Only when an example materially reduces ambiguity. If the process is already clear, skip it.

Size

Minimal. One good example beats three mediocre ones.

Blank Template

Copy this template and fill in the sections. Delete the ones you don't need.

---
name: your-skill-name
description: One sentence: when should this be invoked and what does it accomplish?
---

# Skill Title

## Context
1–3 sentences explaining when this skill applies and what problem it solves.

## Process

1. **First step** — specific enough to execute without guessing.
2. **Second step** — include the why if it is not obvious.
3. **Third step** — what does "done" look like?

## Checklist (remove if fewer than 5 steps)

- [ ] Step one complete
- [ ] Step two verified
- [ ] Step three done

## Anti-Patterns (remove if no common mistakes)

- **Never do X** — because it causes Y.

## Examples (remove if process is already clear)

```
Concrete minimal example here
```

Tip: Use the generator to create a skill file from your actual process in seconds.