> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Skills

> How to create and test new skills using TDD methodology

## Overview

The `writing-skills` skill applies Test-Driven Development principles to creating process documentation. Just as TDD requires writing failing tests before code, skill creation requires testing with agents before writing the skill document.

<Note>
  **Core Principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
</Note>

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools that helps coding agents find and apply effective approaches.

**Skills are:**

* Reusable techniques
* Proven patterns
* Tool documentation
* Reference guides

**Skills are NOT:**

* Narratives about solving one specific problem
* Project-specific conventions (use CLAUDE.md for those)
* Mechanical constraints (automate those instead)

## 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            |
| **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              |
| **Minimal code**        | Write skill addressing specific violations   |
| **Watch it pass**       | Verify agent now complies                    |
| **Refactor cycle**      | Find new rationalizations → plug → re-verify |

## When to Create a Skill

<Accordion title="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 from the knowledge
</Accordion>

<Accordion title="Don't create for:">
  * One-off solutions to specific problems
  * Standard practices well-documented elsewhere
  * Project-specific conventions (use project docs)
  * Mechanical constraints (automate with linters/validation)
</Accordion>

## Skill Types

### Technique

Concrete method with steps to follow.

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

### Pattern

Way of thinking about problems.

**Examples:** flatten-with-flags, test-invariants

### Reference

API docs, syntax guides, tool documentation.

**Examples:** Library APIs, command references

## The RED-GREEN-REFACTOR Cycle

### RED Phase: Write Failing Test

<Steps>
  <Step title="Create Pressure Scenarios">
    Design scenarios that would trigger the problematic behavior (3+ combined pressures for discipline skills).
  </Step>

  <Step title="Run Without Skill">
    Test with a subagent that doesn't have access to the skill. Document exact behavior verbatim.
  </Step>

  <Step title="Identify Patterns">
    Capture the specific rationalizations and failures that occur.
  </Step>
</Steps>

### GREEN Phase: Write Minimal Skill

<Steps>
  <Step title="Create SKILL.md">
    Write a skill that addresses the specific failures identified in RED phase.
  </Step>

  <Step title="Test With Skill">
    Run the same scenarios WITH the skill present. Agent should now comply.
  </Step>
</Steps>

### REFACTOR Phase: Close Loopholes

<Steps>
  <Step title="Find New Rationalizations">
    Test again and capture any new ways agents try to skip the skill.
  </Step>

  <Step title="Add Explicit Counters">
    Update the skill to explicitly forbid each rationalization.
  </Step>

  <Step title="Re-test">
    Verify agents comply with the updated skill.
  </Step>
</Steps>

## SKILL.md Structure

Every skill needs proper frontmatter and clear sections:

```yaml theme={null}
---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---
```

<Accordion title="Frontmatter Requirements">
  * **Only two fields**: `name` and `description`
  * **Max 1024 characters total**
  * **Name format**: Letters, numbers, hyphens only (no special characters)
  * **Description format**:
    * Start with "Use when..."
    * Include specific triggers and symptoms
    * Do NOT summarize the skill's workflow
    * Third-person voice
</Accordion>

<Accordion title="Required Sections">
  1. **Overview** - What is this? Core principle in 1-2 sentences
  2. **When to Use** - Bullet list with symptoms and use cases
  3. **Core Pattern** (for techniques) - Before/after code comparison
  4. **Quick Reference** - Table or bullets for common operations
  5. **Implementation** - Inline code or link to separate file
  6. **Common Mistakes** - What goes wrong + fixes
</Accordion>

## Claude Search Optimization (CSO)

Future agents need to FIND your skill. Optimize for discovery:

### Rich Description Field

**Purpose:** Agents read descriptions to decide which skills to load.

<Warning>
  **CRITICAL:** Description = When to Use, NOT What the Skill Does

  Summarizing workflow in the description causes agents to follow the description instead of reading the full skill. Keep descriptions to triggering conditions only.
</Warning>

```yaml theme={null}
# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task with code review

# ✅ GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks
```

### Keyword Coverage

Use words agents would search for:

* Error messages: "Hook timed out", "ENOTEMPTY"
* Symptoms: "flaky", "hanging", "zombie"
* Synonyms: "timeout/hang/freeze"
* Tool names: Actual commands, libraries

### Descriptive Naming

Use active voice, verb-first:

* ✅ `creating-skills` not `skill-creation`
* ✅ `condition-based-waiting` not `async-test-helpers`

## The Iron Law

```
NO SKILL WITHOUT A FAILING TEST FIRST
```

This applies to NEW skills AND EDITS to existing skills.

**No exceptions:**

* Not for "simple additions"
* Not for "just adding a section"
* Not for "documentation updates"

If you write a skill before testing, delete it and start over.

## Testing Different Skill Types

### Discipline-Enforcing Skills

Test with academic questions and pressure scenarios. Verify compliance under maximum pressure.

### Technique Skills

Test with application scenarios and edge cases. Verify correct application to new scenarios.

### Pattern Skills

Test with recognition and counter-examples. Verify correct identification of when to apply.

### Reference Skills

Test with retrieval and application scenarios. Verify agents find and use information correctly.

## Common Testing Excuses

| Excuse                         | Reality                                  |
| ------------------------------ | ---------------------------------------- |
| "Skill is obviously clear"     | Clear to you ≠ clear to agents. Test it. |
| "It's just a reference"        | References have gaps. Test retrieval.    |
| "Testing is overkill"          | Untested skills always have issues.      |
| "I'll test if problems emerge" | Test BEFORE deploying.                   |
| "Too tedious to test"          | Less tedious than debugging later.       |
| "I'm confident it's good"      | Overconfidence guarantees issues.        |

## Quick Reference

<CardGroup cols={2}>
  <Card title="Full Guide" href="/development/creating-skills" icon="book">
    Comprehensive skill creation guide with examples
  </Card>

  <Card title="Testing Methodology" href="/development/testing-skills" icon="vial">
    Detailed testing process and pressure scenarios
  </Card>
</CardGroup>

## Related Skills

* [Test-Driven Development](/skills/test-driven-development) - The TDD foundation this skill builds on
* [Using Superpowers](/skills/using-superpowers) - How skills are invoked and used