writing-skills

What this skill does

<!--
Adapted from obra/superpowers writing-skills skill (v5.0.7), MIT-licensed,
copyright 2025 Jesse Vincent. Modifications copyright 2026 Joe Amditis.
v0.6.0 ports as a research-category skill: a default-on Research phase is
inserted between "When to Create a Skill" and "Skill Types" so skill design
is grounded in real prior art and current best practice before TDD begins.
Findings land at .superpowers/skill-design-<skill-slug>.md. Skip protocol
text byte-identical to brainstorming/systematic-debugging.
Four cross-references migrated from the upstream namespace prefix to the
local one — three refs to test-driven-development and one to systematic-
debugging; both targets are ported skills so the dual-namespace cross-ref
check requires the local prefix.
SKILL.md is parity:false in the manifest by design.
See CREDITS.md.
-->

# Writing Skills

## Overview

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

**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 

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 superjawn:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances 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 CLAUDE.md)
- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)

## Research phase

Before writing tests for a new skill, gather outside context. This is **default-on**: skip only with explicit, justified statement.

The aim is to ground the skill design in real prior art and current best practice, not just your own recall of patterns.

### 1. Pick research kinds

From the menu — patterns + best practices, prior art, authoritative guidance, user-context.

For writing-skills, the **defaults are: web (skill authoring patterns + recent discourse) and codebase (prior art — does this overlap with an existing skill in this repo or a sibling plugin?)**. Add others when warranted — authoritative when the skill encodes a specific external standard (W3C, RFC, vendor docs), or user-context when prior decisions in memory shape the right shape for the skill.

### 2. Dispatch

Subagent by default:
- `Explore` for codebase / prior-art questions ("does this repo or any installed plugin already have a skill for X?", "what naming convention do existing skills use here?")
- `general-purpose` for web / authoring patterns ("what shape do effective Claude Code skills take?", "common pitfalls for skills in this domain?")
- Run multiple in parallel when the kinds are independent

Inline only for light-touch research (single grep across `~/.claude/skills/`, memory check).

### 3. Record findings

Findings land at `.superpowers/skill-design-<skill-slug>.md` where `<skill-slug>` is the kebab-case name of the skill you are designing. Write 3–5 tight bullets — load-bearing links/refs, prior-art notes, anything considered-but-ruled-out so future-you knows it was checked. The directory `.superpowers/` is git-ignored by upstream convention.

### 4. Skip protocol

If skipping, write one line to `.superpowers/skill-design-<skill-slug>.md`: `Skipped research because <reason>. <Verifiable pointer if applicable>.`

**Valid reasons:**
- Trivial scope (typo, comment edit, single-line config)
- Fresh prior research — same topic in current session OR within last 7 days with verifiable spec/plan pointer. **If the pointer doesn't resolve, the skip is invalid.** (Beyond 7 days, repeat the research even if you remember the prior findings — the landscape drifts.)
- User explicit — **must quote the phrase** that authorized the skip.
- Repeat of identical task — **must include a pointer** to the prior successful run.

**Invalid reasons:** "I think I know", "seems straightforward", "moving fast", "user wants this done quickly", "already familiar with this codebase". If those are tempting, do the research.

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

## SKILL.md Structure

**Frontmatter (YAML):**
- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
- Max 1024 characters total
- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
- `description`: Third-person, describes ONLY when to use (NOT what it does)
  - Start with "Use when..." to focus on triggering conditions
  - Include specific symptoms, situations, and contexts
  - **NEVER summarize the skill's process or workflow** (see CSO section for why)
  - Keep under 500 characters if possible

```markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results
```


## Claude Search Optimization (CSO)

**Critical for discove