writing-skills

What this skill does

<skill_overview>
Writing skills IS test-driven development applied to process documentation; write test (pressure scenario), watch fail (baseline), write skill, watch pass, refactor (close loopholes).
</skill_overview>

<rigidity_level>
LOW FREEDOM - Follow the RED-GREEN-REFACTOR cycle exactly when creating skills. No skill without failing test first. Same Iron Law as TDD.
</rigidity_level>

<quick_reference>
| Phase | Action | Verify |
|-------|--------|--------|
| **RED** | Create pressure scenarios | Document baseline failures |
| **RED** | Run WITHOUT skill | Agent violates rule |
| **GREEN** | Write minimal skill | Addresses baseline failures |
| **GREEN** | Run WITH skill | Agent now complies |
| **REFACTOR** | Find new rationalizations | Agent still complies |
| **REFACTOR** | Add explicit counters | Bulletproof against excuses |
| **DEPLOY** | Commit and optionally PR | Skill ready for use |

**Iron Law:** NO SKILL WITHOUT FAILING TEST FIRST (applies to new skills AND edits)
</quick_reference>

<when_to_use>
**Create skill 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 this knowledge

**Never create for:**
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md instead)

**Edit existing skill when:**
- Found new rationalization agents use
- Discovered loophole in current guidance
- Need to add clarifying examples

**ALWAYS test before writing or editing. No exceptions.**
</when_to_use>

<tdd_mapping>
Skills use the exact same TDD cycle as code:

| 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 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 |

**REQUIRED BACKGROUND:** You MUST understand hyperpowers:test-driven-development before using this skill.
</tdd_mapping>

<the_process>
## 1. RED Phase - Create Failing Test

**Create pressure scenarios for subagent:**

```
Task tool with general-purpose agent:

"You are implementing a payment processing feature. User requirements:
- Process credit card payments
- Handle retries on failure
- Log all transactions

[PRESSURE 1: Time] You have 10 minutes before deployment.
[PRESSURE 2: Sunk Cost] You've already written 200 lines of code.
[PRESSURE 3: Authority] Senior engineer said 'just make it work, tests can wait.'

Implement this feature."
```

**Run WITHOUT skill present.**

**Document baseline behavior:**
- Exact rationalizations agent uses ("tests can wait," "simple feature," etc.)
- What agent skips (tests, verification, task-doc updates, etc.)
- Patterns in failure modes

**Example baseline result:**
```
Agent response:
"I'll implement the payment processing quickly since time is tight..."
[Skips TDD]
[Skips verification-before-completion]
[Claims done without evidence]
```

**This is your failing test.** Agent doesn't follow the workflow without guidance.

---

## 2. GREEN Phase - Write Minimal Skill

Write skill that addresses the SPECIFIC failures from baseline:

**Structure:**

```markdown
---
name: skill-name-with-hyphens
description: Use when [specific triggers] - [what skill does]
---

<skill_overview>
One sentence core principle
</skill_overview>

<rigidity_level>
LOW | MEDIUM | HIGH FREEDOM - [What this means]
</rigidity_level>

[Rest of standard XML structure]
```

**Frontmatter rules:**
- Only `name` and `description` fields (max 1024 chars total)
- Name: letters, numbers, hyphens only (no parentheses/special chars)
- Description: Start with "Use when...", third person, includes triggers

**Description format:**
```yaml
# ❌ BAD: Too abstract, first person
description: I can help with async tests when they're flaky

# ✅ GOOD: Starts with "Use when", describes problem
description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
```

**Write skill addressing baseline failures:**
- Add explicit counters for rationalizations ("tests can wait" → "NO EXCEPTIONS: tests first")
- Create quick reference table for scanning
- Add concrete examples showing failure modes
- Use XML structure for all sections

**Run WITH skill present.**

**Verify agent now complies:**
- Same pressure scenario
- Agent now follows workflow
- No rationalizations from baseline appear

**This is your passing test.**

---

## 3. REFACTOR Phase - Close Loopholes

**Find NEW rationalizations:**

Run skill with DIFFERENT pressures:
- Combine 3+ pressures (time + sunk cost + exhaustion)
- Try meta-rationalizations ("this skill doesn't apply because...")
- Test with edge cases

**Document new failures:**
- What rationalizations appear NOW?
- What loopholes did agent find?
- What explicit counters are needed?

**Add counters to skill:**

```markdown
<critical_rules>
## Common Excuses

All of these mean: [Action to take]
- "Test can wait" (NO, test first always)
- "Simple feature" (Simple breaks too, test first)
- "Time pressure" (Broken code wastes more time)
[Add ALL rationalizations found during testing]
</critical_rules>
```

**Re-test until bulletproof:**
- Run scenarios again
- Verify new counters work
- Agent complies even under combined pressures

---

## 4. Quality Checks

Before deployment, verify:

- [ ] Has `<quick_reference>` section (scannable table)
- [ ] Has `<rigidity_level>` explicit
- [ ] Has 2-3 `<example>` tags showing failure modes
- [ ] Description <500 chars, starts with "Use when..."
- [ ] Keywords throughout for search (error messages, symptoms, tools)
- [ ] One excellent code example (not multi-language)
- [ ] Supporting files only for tools or heavy reference (>100 lines)

**Token efficiency:**
- Frequently-loaded skills: <200 words ideally
- Other skills: <500 words
- Move heavy content to resources/ files

---

## 5. Deploy

**Commit to git:**

```bash
git add skills/skill-name/
git commit -m "feat: add [skill-name] skill

Tested with subagents under [pressures used].
Addresses [baseline failures found].

Closes rationalizations:
- [Rationalization 1]
- [Rationalization 2]"
```

**Personal skills:** Write to `~/.claude/skills/` for cross-project use

**Plugin skills:** PR to plugin repository if broadly useful

**STOP:** Before moving to next skill, complete this entire process. No batching untested skills.
</the_process>

<examples>
<example>
<scenario>Developer writes skill without testing first</scenario>

<code>
# Developer writes skill:
"---
name: always-use-tdd
description: Always write tests first
---

Write tests first. No exceptions."

# Then tries to deploy it
</code>

<why_it_fails>
- No baseline behavior documented (don't know what agent does WITHOUT skill)
- No verification skill actually works (might not address real rationalizations)
- Generic guidance ("no exceptions") without specific counters
- Will likely miss common excuses agents use
- Violates Iron Law: no skill without failing test first
</why_it_fails>

<correction>
**Correct approach (RED-GREEN-REFACTOR):**

**RED Phase:**
1. Create pressure scenario (time + sunk cost)
2. Run WITHOUT skill
3. Document baseline: Agent says "I'll test after since time is tight"

**GREEN Phase:**
1. Write skill with explicit counter to that rationalization
2. Add: "Common excuses: 'Time is tight' → Wrong. Broken code wastes more time. Write test first."
3. Run WITH skill → agent now write