write-a-skill

# Writing Skills

## Process

1. **Gather requirements** — ask user:
   - What task/domain does the skill cover?
   - Is it **Reference** (background knowledge) or **Task** (step-by-step action)?
   - Does it have side effects? (deploy, send message, commit)
   - Does it need executable scripts or just instructions?
   - Any reference materials to include?

2. **Choose content type and invocation mode** (see [Content Type Decision](#content-type-decision) and [Invocation Control](#invocation-control))

3. **Draft the skill** — create:
   - SKILL.md with concise instructions (<500 lines)
   - Additional reference files if content exceeds limit
   - Utility scripts if deterministic operations needed

4. **Validate** — smoke-test with 2-3 realistic prompts (see [Validate & Iterate](#validate--iterate))

5. **Review with user** — present draft and verify against [Review Checklist](#review-checklist)

## Skill Structure

```
skill-name/
├── SKILL.md              # Main instructions (required, <500 lines)
├── reference/            # Detailed docs (loaded on demand)
│   └── api-details.md
├── examples/             # Usage examples (loaded on demand)
│   └── examples.md
├── templates/            # Output templates
│   └── output.md
└── scripts/              # Executable scripts
    └── helper.py
```

Reference attached files in SKILL.md so Claude knows when to load them:

```markdown
## Additional resources
- For complete API details, see [reference/api-details.md](reference/api-details.md)
```

## SKILL.md Template

Use the template at [templates/skill-template.md](templates/skill-template.md).

## Content Type Decision

| Type | Purpose | Invocation | Example |
|------|---------|------------|---------|
| **Reference** | Background knowledge Claude fuses into current work | `user-invocable: false` (Claude auto-loads when relevant) | coding-style, api-conventions |
| **Task** | Step-by-step action with concrete output | Default or `disable-model-invocation: true` | deploy, create-component, review-pr |

Reference-only skills should not set `context: fork` — a subagent receiving guidelines without a concrete task returns nothing useful. Fork is for executable tasks that need context isolation.

## Invocation Control

| Scenario | Frontmatter | Why |
|----------|-------------|-----|
| General tool (no side effects) | (default) | Both user and Claude can trigger |
| **Has side effects** (deploy, commit, send) | `disable-model-invocation: true` | Prevents Claude from auto-triggering destructive actions without user intent |
| Background knowledge | `user-invocable: false` | Claude auto-loads when relevant, hidden from `/` menu |
| Isolated heavy task | `context: fork` | Runs in subagent to protect main context from token bloat |

## Description as Testable Hypothesis

For auto-triggerable skills (the default and `user-invocable: false`), the description is **the only thing Claude sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills — treat it as a testable hypothesis, not a one-time label. (Skills with `disable-model-invocation: true` are never auto-discovered by Claude, so description quality matters less for triggering — but still write a clear one for humans browsing the `/` menu.)

**Writing rules**:
- Max 1024 chars
- First sentence: what it does
- Second sentence: "Use when [specific triggers]" — include keywords users would naturally say
- Write trigger conditions, NOT a feature summary
- For auto-triggerable skills, lean slightly "pushy" — Claude tends to under-trigger, so err on the side of broader matching

```yaml
# BAD — feature summary, no trigger signals
description: A tool for monitoring pull requests

# GOOD — trigger-oriented, includes user vocabulary
description: >
  Monitor open PRs and report CI status changes.
  Use when user says babysit, watch CI, monitor PRs,
  or check pipeline status.
```

**Verifying triggers**: After writing the description, mentally test it against a few prompts — would Claude choose this skill for "hey can you keep an eye on my PR"? What about "check if CI passed"? If the answer is unclear, revise. For formal trigger optimization with train/test splits, see [reference/eval-workflow.md](reference/eval-workflow.md).

## Writing Principles

1. **Don't state the obvious** — Claude already knows programming. Only write what Claude does NOT know by default: team conventions, project-specific context, gotchas, workarounds.

2. **Constrain goals, not paths** — Specify WHAT to achieve, not a rigid step order. Let Claude adapt based on context:

   ```markdown
   # BAD — rigid steps
   1. Run `npm test`  2. Run `npm run lint`  3. Deploy

   # GOOD — goal-oriented
   Ensure code passes all tests and lint checks, then deploy.
   Adapt order based on current state.
   ```

3. **Explain the why, not just the rule** — When you need Claude to follow a constraint, explain the reasoning behind it. Claude has good theory of mind — understanding *why* something matters produces better results than rigid directives. If you find yourself writing ALWAYS or NEVER in all caps, that's a signal to reframe: explain the reasoning so Claude understands the intent and can apply good judgment in edge cases.

   ```markdown
   # Weaker — bare directive
   ALWAYS use the legacy API endpoint.

   # Stronger — explains why
   Use the legacy API endpoint — the v2 endpoint doesn't support
   batch operations yet, and our workflow depends on batching.
   ```

4. **Build a Gotchas section** — The highest-signal content in any skill. Only your team has this knowledge. Every time a skill execution hits an unexpected failure, write the failure pattern back into Gotchas. This iteration loop is what makes a skill improve over time — without it, the same mistake repeats forever.

5. **Include completion criteria** — Every task skill should define a "Definition of Done" so Claude knows when to stop. Without this, Claude may over-deliver o