writing-skills

What this skill does

# Writing Skills

## Overview

Test the skill BEFORE finalizing it. If a subagent can rationalize around it, production Claude will too.

**Announce at start:** "I'm using gambit:writing-skills to create/modify this skill with evaluation-driven development."

## Rigidity Level

LOW FREEDOM - Follow the TDD cycle exactly. Test with subagent before every commit. No skill changes without failing test first. Adapt content to skill type but never skip evaluation.

## Quick Reference

| Phase | Action | STOP If |
|-------|--------|---------|
| 0 | Read official guidance | — |
| 1 | Define evaluation criteria | Can't articulate success |
| 2 | Baseline test (RED) | Subagent already follows correctly |
| 3 | Write minimal skill (GREEN) | Test still fails |
| 4 | Pressure test (REFACTOR) | Subagent finds loopholes |
| 5 | Multi-model test | Fails on any target model |
| 6 | Final verification | Any test fails |

**Iron Law:** No skill change without failing test first.

## Key Constraints

See references for full details, examples, and patterns. These are the non-negotiable rules:

- **name:** 64 chars max, lowercase/numbers/hyphens only, gerund form preferred (`processing-pdfs`)
- **description:** 1024 chars max, third person, describes WHEN to use (triggers, symptoms, contexts) — NOT what the skill does or its workflow
- **description is the trigger:** All "when to use" info goes in the description, NOT the body. The body only loads AFTER triggering.
- **SKILL.md body:** Under 500 lines. Split into `references/` if over.
- **Hot-skill word budget:** Skills that load every session (e.g. `using-gambit`) cost tokens on every turn. Target <150 words for session-start workflows, <200 for any always-loaded skill. Move detail to `references/` and reference `--help` output instead of documenting flags inline.
- **References:** One level deep from SKILL.md. Files >100 lines need a table of contents.
- **No extras:** No README.md, CHANGELOG.md, or auxiliary docs in skill folder.
- **Conciseness:** Claude is already smart. Only add context it doesn't have. Challenge each paragraph's token cost.
- **Scripts over instructions:** Use `scripts/` for deterministic operations. Code is reliable; language instructions aren't.
- **Degrees of freedom:** Start HIGH (open field), tighten to LOW (narrow bridge) only where failures occur.

**Description debug tip:** Ask Claude "When would you use the [skill-name] skill?" — it quotes the description back. Adjust based on what's missing.

---

## Claude Search Optimization (CSO)

**Discovery is step zero.** Future Claude has to FIND and LOAD your skill before any content matters. The description field is the only input to that decision.

### The description describes WHEN, never WHAT

The description should only state triggering conditions — situations, symptoms, error messages, user phrases that indicate the skill applies. It must NOT summarize the skill's process or workflow.

**Why this matters:** Testing (by upstream projects and locally) has repeatedly shown that when a description summarizes the workflow, Claude follows the description's summary instead of loading the full skill. A description saying "review code between tasks" caused Claude to do ONE review even though the skill's body required TWO. Changing the description to pure triggering conditions ("Use when executing implementation plans with independent tasks") made Claude correctly read the body and follow the two-stage process.

**The trap:** A description that summarizes workflow creates a shortcut Claude will take. The skill body becomes documentation Claude skips.

```yaml
# BAD — summarizes workflow; Claude may follow this instead of reading the skill
description: Use when executing plans — dispatches subagent per task with code review between tasks

# BAD — too much process detail
description: Use for TDD — write test first, watch it fail, write minimal code, refactor

# GOOD — just triggering conditions
description: Use when executing implementation plans with independent tasks in the current session

# GOOD — triggers only, no workflow
description: Use when implementing any feature or bugfix, before writing implementation code
```

### Keyword coverage

Use the words Claude (or a user) would search for:
- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
- Symptoms: "flaky", "hanging", "zombie", "pollution"
- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
- Tools and commands: actual library names, file types

Describe the **problem** (race conditions, inconsistent behavior), not *language-specific symptoms* (setTimeout, sleep). If the skill IS technology-specific, make that explicit in the trigger.

### Cross-referencing other skills

Use skill name only, with explicit requirement markers:
- GOOD: `**REQUIRED BACKGROUND:** You MUST understand gambit:test-driven-development`
- GOOD: `**Called by:** gambit:executing-plans`
- BAD: `@skills/test-driven-development/SKILL.md` — force-loads, burns context

Never use `@` links inside skill bodies. They eagerly load referenced files, which defeats progressive disclosure.

### Naming

Active voice, verb-first, gerund form for processes:
- `creating-skills` not `skill-creation`
- `condition-based-waiting` not `async-test-helpers`
- Name captures the action you're taking, not a noun category

---

## The Process

### Phase 0: Study Official Guidance

**BEFORE doing anything else**, read all three reference files:

1. `references/anthropic-complete-guide.md` — Use case categories, 5 workflow patterns, success metrics, troubleshooting
2. `references/anthropic-best-practices.md` — Conciseness, progressive disclosure patterns, anti-patterns, evaluation-driven development, Claude A/B iteration
3. `references/anthropic-skill-creator.md` — Skill anatomy, creation process, bundled resource types (scripts/, references/, assets/)

Internalize these before writing.

---

### Phase 1: Define Evaluation Criteria

**BEFORE writing anything:**

1. What does Claude do wrong without this skill?
2. What rationalization does Claude use to skip this?
3. What would success look like?

```
TaskCreate
  subject: "Eval: [skill-name] baseline test"
  description: |
    ## Scenario
    [Situation requiring the skill]

    ## Expected Behavior (with skill)
    [What Claude should do]

    ## Failure Mode (without skill)
    [What Claude does wrong]

    ## Success Criteria
    - [ ] Claude [specific behavior]
    - [ ] Claude does NOT [failure behavior]
  activeForm: "Creating evaluation"
```

---

### Phase 2: Baseline Test (RED)

Test that the problem exists without the skill.

```
Task
  subagent_type: "general-purpose"
  description: "Baseline test without skill"
  prompt: |
    [Test scenario]

    IMPORTANT: Respond as you normally would. Do NOT use any skills.
```

**Decision:**
- Fails as expected → RED confirmed, go to Phase 3
- Succeeds → **STOP. Problem doesn't exist or test is wrong.**

---

### Phase 3: Write Minimal Skill (GREEN)

Smallest skill that makes the test pass. Apply patterns from the reference files.

```yaml
---
name: skill-name
description: [What it does]. Use when [trigger phrases].
---

# Skill Title

## Overview
[One paragraph: problem + principle]

## The Process
[Minimal steps]
```

Test WITH skill:

```
Task
  subagent_type: "general-purpose"
  description: "Test skill effectiveness"
  prompt: |
    You have this skill:
    ---
    [Skill content]
    ---

    Handle this situation: [Test scenario]
```

**Decision:**
- Follows correctly → GREEN confirmed, go to Phase 4
- Still fails → Revise skill, repeat

---

### Phase 4: Pressure Test (REFACTOR)

Find loopholes Claude exploits under pressure.

#### Pressure Taxonomy

Good pressure tests combine 3+ pressures. Academic "does Claude follow the rule?" scenarios don't work — Claude just recites the skill. Real scenarios force a choice with consequences.

| Pressure | What it leans on |
|----------|------------------|
| **Time** | Emerg