git:20260919.2c4bbac to git:20261021.e9d05f9

---

name: writing-skills

description: Use when creating new skills, editing existing skills, or verifying skills work before deployment

---

# Writing Skills

## Overview

**Writing skills IS Test-Driven Development applied to process documentation.**

**Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.

**Skills are:** Reusable techniques, patterns, tools, reference guides

**Skills are NOT:** Narratives about how you solved a problem once

## TDD Mapping for Skills

| TDD Concept | Skill Creation |

|-------------|----------------|

| **Test case** | Pressure scenario with subagent |

| **Production code** | Skill document (SKILL.md) |

| **Test fails (RED)** | Agent violates rule without skill (baseline) |

| **Test passes (GREEN)** | Agent complies with skill present |

| **Refactor** | Close loopholes while maintaining compliance |

| **Write test first** | Run baseline scenario BEFORE writing skill |

| **Watch it fail** | Document exact rationalizations agent uses |

| **Minimal code** | Write skill addressing those specific violations |

| **Watch it pass** | Verify agent now complies |

| **Refactor cycle** | Find new rationalizations → plug → re-verify |

The entire skill creation process follows RED-GREEN-REFACTOR.

## When to Create a Skill

**Create when:**

- Technique wasn't intuitively obvious to you

- You'd reference this again across projects

- Pattern applies broadly (not project-specific)

- Others would benefit

**Don't create for:**

- One-off solutions

- Standard practices well-documented elsewhere

- Project-specific conventions (put in your instructions file)

- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)

## Skill Types

### Technique

Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)

### Pattern

Way of thinking about problems (flatten-with-flags, test-invariants)

### Reference

API docs, syntax guides, tool documentation (office docs)

## Directory Structure

```

skills/

skill-name/

SKILL.md # Main reference (required)

supporting-file.* # Only if needed

```

**Flat namespace** - all skills in one searchable namespace

**Separate files for:**

1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax

2. **Reusable tools** - Scripts, utilities, templates

**Keep inline:**

- Principles and concepts

- Code patterns (< 50 lines)

- Everything else

## Code Examples

**One excellent example beats many mediocre ones**

Choose most relevant language:

- Testing techniques → TypeScript/JavaScript

- System debugging → Shell/Python

- Data processing → Python

**Good example:**

- Complete and runnable

- Well-commented explaining WHY

- From real scenario

- Shows pattern clearly

- Ready to adapt (not generic template)

**Don't:**

- Implement in 5+ languages

- Create fill-in-the-blank templates

- Write contrived examples

You're good at porting - one great example is enough.

## File Organization

### Self-Contained Skill

```

defense-in-depth/

SKILL.md # Everything inline

```

When: All content fits, no heavy reference needed

### Skill with Reusable Tool

```

condition-based-waiting/

SKILL.md # Overview + patterns

example.ts # Working helpers to adapt

```

When: Tool is reusable code, not just narrative

### Skill with Heavy Reference

```

pptx/

SKILL.md # Overview + workflows

pptxgenjs.md # 600 lines API reference

ooxml.md # 500 lines XML structure

scripts/ # Executable tools

```

When: Reference material too large for inline

Invoke bundled scripts through their interpreter in the prose (`bash scripts/tool.sh`, `node scripts/tool.js`), never by bare path: some harness plugin packagers strip executable bits, and a bare `scripts/tool.sh` fails there with `Permission denied`.

## The Iron Law (Same as TDD)

```

NO SKILL WITHOUT A FAILING TEST FIRST

```

This applies to NEW skills AND EDITS to existing skills.

Write skill before testing? Delete it. Start over.

Edit skill without testing? Same violation.

**No exceptions:**

- Not for "simple additions"

- Not for "just adding a section"

- Not for "documentation updates"

- Don't keep untested changes as "reference"

- Don't "adapt" while running tests

- Delete means delete

**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.

## Testing All Skill Types

Different skill types need different test approaches:

### Discipline-Enforcing Skills (rules/requirements)

**Examples:** TDD, verification-before-completion, designing-before-coding

**Test with:**

- Academic questions: Do they understand the rules?

- Pressure scenarios: Do they comply under stress?

- Multiple pressures combined: time + sunk cost + exhaustion

- Identify rationalizations and add explicit counters

**Success criteria:** Agent follows rule under maximum pressure

### Technique Skills (how-to guides)

**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming

**Test with:**

- Application scenarios: Can they apply the technique correctly?

- Variation scenarios: Do they handle edge cases?

- Missing information tests: Do instructions have gaps?

**Success criteria:** Agent successfully applies technique to new scenario

### Pattern Skills (mental models)

**Examples:** reducing-complexity, information-hiding concepts

**Test with:**

- Recognition scenarios: Do they recognize when pattern applies?

- Application scenarios: Can they use the mental model?

- Counter-examples: Do they know when NOT to apply?

**Success criteria:** Agent correctly identifies when/how to apply pattern

### Reference Skills (documentation/APIs)

**Examples:** API documentation, command references, library guides

**Test with:**

- Retrieval scenarios: Can they find the right information?

- Application scenarios: Can they use what they found correctly?

- Gap testing: Are common use cases covered?

**Success criteria:** Agent finds and correctly applies reference information

## Common Rationalizations for Skipping Testing

| Excuse | Reality |

|--------|---------|

| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |

| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |

| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |

| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |

| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |

| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |

| "Academic review is enough" | Reading ≠ using. Test application scenarios. |

| "No time to test" | Deploying untested skill wastes more time fixing it later. |

**All of these mean: Test before deploying. No exceptions.**

## Match the Form to the Failure

Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.

| Baseline failure | Right form | Wrong form |

|---|---|---|

| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") |

| Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |

| Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses |

**Why prohibitions backfire on shaping problems:** under a competing incentive ("make the prompt self-contained"), agents negotiate with "don't X". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than the recipe arm (fully separated distributions), and trended worse than even the no-guidance control — micro-test your own case rather than assuming, but never reach for the prohibition by default. A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't.

**Rules for whichever form you pick:**

- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.

- **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.

## RED-GREEN-REFACTOR for Skills

Follow the TDD cycle:

### RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:

- What choices did they make?

- What rationalizations did they use (verbatim)?

- Which pressures triggered violations?

This is "watch the test fail" - you must see what agents naturally do before writing the skill.

### GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.

Run same scenarios WITH skill. Agent should now comply.

### REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

### Micro-Test Wording Before Full Scenarios

Full pressure-scenario runs are the final gate, but they are slow and expensive per iteration. Verify the wording itself first with micro-tests:

1. **One fresh-context sample per call** — a raw API call, or a single-shot subagent if you don't have API access. System prompt = the realistic context the guidance will live in (the full skill or prompt template, not the guidance in isolation); user message = a task that tempts the failure.

2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance.

3. **5+ reps per variant.** Single samples lie.

4. **Manually read every flagged match.** Score programmatically if you like, but template echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both failure and success.

5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five different interpretations across five reps means the wording isn't binding — tighten the form before adding words.

Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.

- How to write pressure scenarios

- Pressure types (time, sunk cost, authority, exhaustion)

- Plugging holes systematically

- Meta-testing techniques

## Anti-Patterns

### ❌ Narrative Example

"In session 2025-10-03, we found empty projectDir caused..."

**Why bad:** Too specific, not reusable

### ❌ Multi-Language Dilution

example-js.js, example-py.py, example-go.go

**Why bad:** Mediocre quality, maintenance burden

### ❌ Code in Flowcharts

```dot

step1 [label="import fs"];

step2 [label="read file"];

```

**Why bad:** Can't copy-paste, hard to read

### ❌ Generic Labels

helper1, helper2, step3, pattern4

**Why bad:** Labels should have semantic meaning

## STOP: Before Moving to Next Skill

**After writing ANY skill, you MUST STOP and complete the deployment process.**

**Do NOT:**

- Create multiple skills in batch without testing each

- Move to next skill before current one is verified

- Skip testing because "batching is more efficient"

**The deployment checklist below is MANDATORY for EACH skill.**

Deploying untested skills = deploying untested code. It's a violation of quality standards.

## Skill Creation Checklist (TDD Adapted)

**IMPORTANT: Create a todo for EACH checklist item below.**

**RED Phase - Write Failing Test:**

- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)

- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim

- [ ] Identify patterns in rationalizations/failures

**GREEN Phase - Write Minimal Skill:**

- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)

- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))

- [ ] Description starts with "Use when..." and includes specific triggers/symptoms

- [ ] Description written in third person

- [ ] Keywords throughout for search (errors, symptoms, tools)

- [ ] Clear overview with core principle

- [ ] Address specific baseline failures identified in RED

- [ ] Guidance form matches the failure type (see Match the Form to the Failure)

- [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills

- [ ] Code inline OR link to separate file

- [ ] One excellent example (not multi-language)

- [ ] Run scenarios WITH skill - verify agents now comply

**REFACTOR Phase - Close Loopholes:**

- [ ] Identify NEW rationalizations from testing

- [ ] Add explicit counters (if discipline skill)

- [ ] Build rationalization table from all test iterations

- [ ] Create red flags list

- [ ] Re-test until bulletproof

**Quality Checks:**

- [ ] Small flowchart only if decision non-obvious

- [ ] Quick reference table

- [ ] Common mistakes section

- [ ] No narrative storytelling

- [ ] Supporting files only for tools or heavy reference

**Deployment:**

- [ ] Commit skill to git and push to your fork (if configured)

- [ ] Consider contributing back via PR (if broadly useful)

## Discovery Workflow

How future agents find your skill:

1. **Encounters problem** ("tests are flaky")

2. **Searches skills** (greps descriptions, browses categories)

3. **Finds SKILL** (description matches)

4. **Scans overview** (is this relevant?)

5. **Reads patterns** (quick reference table)

6. **Loads example** (only when implementing)

**Optimize for this flow** - put searchable terms early and often.