create-skill

어떤 스킬인가요?

Use when creating, editing, scaffolding, designing, reviewing, improving, or refactoring a Claude Code skill, slash command, subagent, or agent capability. Also use when extracting a repeatable workflow from the current session into a reusable skill. Trigger phrases include "create skill", "build skill", "scaffold skill", "edit skill", "write skill", "design skill", "improve skill", "fix skill", "review skill", "audit skill", "refactor skill", "new slash command", "new subagent", "turn this workflow into a skill", "turn this into a skill", "extract skill from session", "skillify this", "save this workflow as a skill", "add a skill", "authoring skills", "writing skills".

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Skill Design

How to analyze a domain, design the file structure, and apply progressive disclosure.

## Step 0: Classify the skill type

Before designing anything, determine which type of skill you're building. This decision drives every downstream choice — file structure, discipline level, verification method.

| Signal | Type | What it means |
|---|---|---|
| Orchestrates agents, makes completion claims, has multi-stage state | **Workflow** | Full discipline: pressure-tests, counter-tables, termination labels, iron-law gates, companion split at 300 lines |
| Teaches how to use a tool, API, CLI, or library | **Reference** | Guide with code examples, `references/` subdirectory, accuracy verification instead of pressure-tests |
| Routes to another skill or deprecates an old name | **Shim** | ~15 lines, SKILL.md only, exempt from all discipline |

**Decision test:** Ask "does this skill orchestrate agent behavior under pressure, or does it teach a human/agent how to use a tool?" If it orchestrates → workflow. If it teaches → reference. If it just redirects → shim.

Common reference skill domains: MCP server guides, CLI wrappers, API references, infrastructure tool guides, platform integration docs.

Common workflow skill domains: code review orchestrators, test runners, design critics, research coordinators, deployment pipelines.

Misclassifying a reference skill as workflow adds bureaucratic overhead (counter-tables, pressure-tests) that doesn't prevent real failure modes. Misclassifying a workflow skill as reference removes the discipline that prevents agent rationalization under pressure. Get this right.

## Step 1: Understand the domain

Before designing anything, answer these questions. If you can't answer them, ask the user.

### What does the skill do?

Write a single sentence: "This skill [verb]s [object] by [method]."

Examples:
- "This skill builds digital board games by implementing rules engines and rendering game UIs in a single HTML file."
- "This skill generates API clients by reading OpenAPI specs and producing typed TypeScript code."
- "This skill reviews pull requests by analyzing diffs against project conventions and producing structured feedback."

If the sentence has "and" more than once, the skill is too broad. Split it.

### When should it trigger?

List the exact phrases a user would say:
- "build a chess game" → board game skill
- "create an API client for Stripe" → API client skill
- "review this PR" → PR review skill

Also list when it should NOT trigger:
- "explain how chess works" → this is a question, not a build request
- "fix the API client bug" → this is a bug fix, not generation

These become the `description` keywords and the negative test cases.

### What does it produce?

- Files? Which ones, what format?
- Terminal output? What structure?
- Side effects? (git commits, API calls, file writes)

### What tools does it need?

- Read/Write/Edit for file operations
- Bash for running commands
- Glob/Grep for searching
- External tools (Playwright, npm, etc.)

If the skill needs specific tools, add `allowed-tools` to frontmatter.

### What can go wrong?

List the top 5-10 failure modes. These become:
- Golden rules (preventive)
- Self-review checklist items (detective)
- Failure diagnosis table entries (corrective)

## Step 2: Design the file structure

### The two-level rule

Every skill has exactly two levels of content:

```
my-skill/
├── SKILL.md           # Level 1: map (always loaded on trigger)
└── reference files     # Level 2: details (loaded when Claude reads them)
```

SKILL.md points to reference files. Reference files do NOT point to other reference files. This is the "one level deep" rule. Deeply nested references cause Claude to partially read files and miss information.

### The 300-line companion-split threshold

If the skill's total content (SKILL.md + all reference files) exceeds 300 lines, switch to the npow orchestration companion split:

```
my-skill/
├── SKILL.md           # lean map only — workflow, golden rules, counter-table, labels
├── FORMAT.md          # output templates and schemas for every artifact the skill produces
├── STATE.md           # state.json schema, resume protocol, pre-transition gate checks
├── GOLDEN-RULES.md    # rules with concrete examples + full anti-rationalization counter-table
├── INTEGRATION.md     # composition with deep-qa, deep-design, degraded-mode fallbacks
└── pressure-tests/
    ├── scenarios.md
    ├── baseline.md
    └── with-skill.md
```

This is mandatory above 300 lines. It's not bureaucracy — long SKILL.md bodies get partial-read by Claude, and the split enables progressive disclosure. See [FORMAT.md](FORMAT.md) for templates.

### How to split content

| Content type | Where it goes | Why |
|---|---|---|
| Workflow steps (numbered, one-line each) | SKILL.md | Claude needs the overview immediately |
| Self-review checklist | SKILL.md | Must be checked every time |
| Golden rules | SKILL.md | Must be visible every time |
| Reference file index | SKILL.md | Map to deeper content |
| Code patterns and templates | Reference file | Only needed when implementing |
| Detailed step instructions | Reference file | Only needed when on that step |
| Examples and samples | Reference file | Only needed when relevant |
| Testing methodology | Reference file | Only needed during testing phase |
| Visual/style standards | Reference file | Only needed during UI work |
| Domain-specific reference (APIs, schemas) | Reference file | Only needed for specific questions |

### How many reference files?

- **1-2 files**: Simple skills (conventions, style guides, single-tool workflows, under 300 lines total)
- **3-5 files**: Medium skills (multi-step workflows, 300-800 lines — companion split applies)
- **6-8 files**: Complex skills (orchestrators, full application builders, 800+ lines — companion split + extra reference files)
- **More than 8**: The skill is too broad. Split into multiple skills.

Above 300 lines total, the core five files are always: SKILL.md, FORMAT.md, STATE.md (if workflow), GOLDEN-RULES.md, INTEGRATION.md. Extra topic-specific reference files come on top of those five.

### Naming reference files

Use descriptive names that indicate content:

Good: `TESTING.md`, `VISUAL.md`, `ARCHITECTURE.md`, `WORKFLOW.md`
Bad: `DETAILS.md`, `MORE.md`, `PART2.md`, `REFERENCE.md`

Claude uses filenames as signals for relevance. `TESTING.md` is clearly about testing. `DETAILS.md` could be about anything.

### Scripts and executable content

If the skill involves running commands, consider bundling scripts:

```
my-skill/
├── SKILL.md
├── TESTING.md
└── scripts/
    ├── validate.sh    # Claude runs this, doesn't read it
    └── template.html  # Claude copies/adapts this
```

Scripts are more reliable than generated code — Claude executes them without consuming context tokens for the script body.

## Step 3: Apply progressive disclosure

### What loads when

| Phase | What Claude sees | Token cost |
|---|---|---|
| Startup | `name` + `description` from all skills | ~100 tokens per skill |
| Trigger | SKILL.md body | The full file |
| As-needed | Reference files, one at a time | Only when read |

### Design for minimal initial load

SKILL.md should contain ONLY:
- The workflow (numbered steps, one line each)
- The self-review checklist
- The golden rules
- The reference file index

Everything else goes in reference files. This keeps the initial context load small and focused.

### Design for selective reference loading

Not every task needs every reference file. Structure reference files so Claude can determine from the filename and the one-line summary in SKILL.md whether it needs that file.

Example: A board game skill has `MULTIPLAYER.md`. If the user asks for a single-player solitaire game, Claude won't need to read it. The one-line summary in SKILL.md ("Host-authoritative model, hidden info, networking...") tells Claude it's not relevant.

### Long reference files: add a table of contents

If a reference file exceeds 100 lines, add a table of contents at the top:

```markdown
# Architecture Patterns

## Contents
- State management pattern
- Grid-based boards
- Card-based games
- AI opponent (minimax)
- Undo system
```

This helps Claude navigate to the right section without reading the entire file.

## Step 3.5: Flowchart usage rules

Flowcharts are expensive (they render inconsistently, take vertical space, and are ultimately read linearly — eliminating their non-linear advantage). Use them only where they pay for themselves.

### ✅ Use flowcharts for
- **Non-obvious decision points** where an agent might branch the wrong way
- **Process loops** where an agent might stop too early (pressure-test loops, verification loops, retry limits)
- **"When to use A vs B"** decisions between similar skills or patterns

### ❌ Never use flowcharts for
- **Reference material** — use tables or lists
- **Linear instructions** — use numbered lists
- **Code examples** — use markdown code blocks (not node labels inside a flowchart)
- **Labels without semantic meaning** — nodes named `step1`, `helper2`, `branch3` are worse than no flowchart

### Format requirements
- Every node label carries semantic meaning (no `step1`, `helper2`)
- Edge labels ("yes" / "no", or specific conditions) are always present
- Flowchart fits on one screen (≤10 nodes in SKILL.md bodies; ≤20 in reference files)
- Rendering: use `dot` / graphviz syntax inside a ` ```dot ` code block — Claude parses this reliably

## Step 4: Decide invocation settings

### Who invokes the skill?

| Setting | Use case |
|---|---|
| Default (both user and Claude) | Most skills — Claude triggers when relevant, user can also `/invoke` |
| `disable-model-invocation: true` | Dangerous operations (deploy, publish, delete) — user triggers only |
| `user-invocable: false` | Background knowledge (conventions, context) — Claude uses as needed |

### Should it fork?

Add `context: fork` when:
- The skill is a self-contained task (research, analysis, generation)
- It doesn't need conversation history
- Its output is a complete deliverable (a file, a report, a plan)

Do NOT fork when:
- The skill provides conventions/context that apply to the current conversation
- It needs to interact with the user mid-task
- Its guidance applies across multiple tool calls

## Reference skill design

Reference skills follow a different design path than workflow skills. They don't orchestrate agents — they teach how to use a tool. Design accordingly.

### Purpose sentence

Same format as workflow: "This skill teaches how to use [tool] for [task]."

Examples:
- "This skill teaches how to use the Maestro MCP server to inspect and debug Metaflow workflow runs."
- "This skill teaches how to use the Slack API scripts for reading messages, sending replies, and searching."

### Core operations

List the 5-10 most common things a user does with this tool. These become the quick-reference table in SKILL.md and the sections in `references/`.

### File structure

```
my-reference-skill/
├── SKILL.md                 # Guide: purpose, quick-reference table, code examples, golden rules
├── references/              # Overflow content, each file ≤500 lines
│   ├── quick-start.md       # Getting started (optional)
│   ├── api-reference.md     # Endpoint/CLI details (optional)
│   ├── troubleshooting.md   # Common errors and fixes (optional)
│   └── examples/            # Worked examples (optional)
└── verification/
    └── commands-tested.md   # 3-5 tested commands with output and PASS/FAIL
```

Reference skills do NOT use FORMAT.md, STATE.md, GOLDEN-RULES.md, or INTEGRATION.md. Those are the workflow companion pattern.

### Golden rules for reference skills

Reference skills still need 3-8 golden rules, but they're about the tool, not about agent discipline:

- "Never run `X` without `--dry-run` first" (destructive operation guard)
- "Always use the authenticated API wrapper for Jenkins calls, not plain `curl`" (auth requirement)
- "Never suppress stderr — the script writes errors there" (silent failure prevention)

### Reference skill checklist

- [ ] Purpose sentence written
- [ ] Core operations listed (5-10)
- [ ] Quick-reference table in SKILL.md
- [ ] Code examples tested and working
- [ ] Golden rules are tool-specific (3-8)
- [ ] `references/` directory for overflow content
- [ ] `verification/commands-tested.md` with 3-5 commands, all PASS
- [ ] Description has trigger keywords ("Use when...")

## Checklist before moving to writing (workflow skills)

- [ ] Single-sentence purpose statement written
- [ ] Trigger phrases listed (positive and negative)
- [ ] Output format defined
- [ ] Required tools identified
- [ ] Failure modes listed (5-10)
- [ ] File structure designed (flat or companion-split based on 300-line threshold)
- [ ] Each reference file has a clear name and single responsibility
- [ ] Invocation settings decided
- [ ] Pressure scenarios drafted (3-5, at least 2 pressure types) — see [PRESSURE-TESTING.md](PRESSURE-TESTING.md). These are authored BEFORE SKILL.md is written.
- [ ] Termination labels sketched (if workflow) — see [FORMAT.md](FORMAT.md) mandatory section 5.
- [ ] Integration decisions made: will the skill invoke `deep-qa` for self-review? `deep-design` for design review? — see [INTEGRATION.md](INTEGRATION.md).

# Skill Evaluation

How to test skills, verify they work, and iterate based on real usage.

**Note on scope:** This document covers the discovery/invocation test layer — does the skill activate for the right prompts and produce the right output shape? The complementary discipline-under-pressure layer is covered in [PRESSURE-TESTING.md](PRESSURE-TESTING.md), which runs BEFORE this evaluation. Both layers are required. Pressure testing catches rationalization; evaluation catches trigger misses, noisy-context failures, and false positives.

## Test prompt categories

**Note:** The test categories below apply to all skill types. The verification protocol (Phase 1) has type-specific checks — see below.

Every skill should be tested with 4 types of prompts. Write 3-5 prompts per category.

### 1. Explicit invocation

User directly names the skill or its exact purpose:

```
/create-skill a PR review assistant
Create a skill for generating changelogs
Build me a board game skill
```

**What to verify**: Skill activates. Workflow starts from step 1. All reference files are accessible.

### 2. Implicit invocation

User describes a need that matches the skill's description keywords, without naming it:

```
I need Claude to automatically review my code
Help me set up a slash command for deployments
I want to digitize Settlers of Catan
```

**What to verify**: Skill activates from description matching. Same quality output as explicit invocation.

### 3. Contextual (noisy) prompts

Realistic prompts with extra context, ambiguity, or constraints:

```
We're using a monorepo with turborepo and I need a skill that runs our specific test suite across packages — it should understand our workspace structure
I want a board game thing but specifically for a homebrew card game my friend designed, here are the rules [long rules dump]
```

**What to verify**: Skill activates and handles the extra context. Doesn't get confused by irrelevant details. Extracts the relevant requirements.

### 4. Negative controls

Prompts where the skill should NOT activate:

```
What is a skill?                          → question, not creation
Fix the bug in my existing skill          → editing, not creating
How do skills work in Claude Code?        → documentation query
```

**What to verify**: Skill does NOT activate. Claude handles the request normally.

## Verification protocol

After writing a skill, run it through this verification sequence:

### Phase 1: Structure check

Without running the skill, manually inspect the files:

```
1. Count SKILL.md content lines (target: 50-100 for flat skills; ≤150 for companion-split maps)
2. Verify zero code blocks in SKILL.md **(workflow skills only — reference skills may have code blocks)**
3. Verify all reference files are linked from SKILL.md
4. Verify reference files are under 500 lines each
5. Verify description contains trigger keywords and does NOT summarize workflow
6. Verify golden rules use imperative language (no "should", "consider", "try to", "prefer")
7. Verify self-review checklist items are objectively verifiable
8. Verify at least one feedback loop exists
9. Verify anti-rationalization counter-table exists with min 5 rows (discipline) or 3 rows (one-shot)
10. Verify termination labels section exists and is a finite enum (workflow skills only)
11. Verify iron-law gate language in completion claims (concrete file-existence check, not "verify")
12. Verify companion split applied if total content > 300 lines
13. Verify `pressure-tests/scenarios.md`, `baseline.md`, `with-skill.md` all exist on disk
14. Verify `pressure-tests/with-skill.md` shows zero unaddressed rationalizations
15. **(Reference skills only)** Verify `verification/commands-tested.md` exists with 3-5 tested commands, all PASS
16. **(Reference skills only)** Verify `references/` subdirectory exists if skill content exceeds SKILL.md alone
```

If `deep-qa` is installed, running it against the skill at `--type skill` runs a parallel-critic audit across these dimensions. See [INTEGRATION.md](INTEGRATION.md).

### Phase 2: Dry run

Mentally trace through the workflow for a specific use case:

```
1. Pick a concrete example (e.g., "create a skill for reviewing Python code")
2. Walk through each workflow step
3. For each step, check: does the instruction tell me EXACTLY what to do?
4. For each step, check: does the reference file contain the detail I need?
5. At the self-review checklist, check: can I verify each item right now?
6. At the golden rules, check: did I violate any during the dry run?
```

If you get stuck at any step, the skill needs more detail at that point.

### Phase 3: Live test

Actually invoke the skill and use it to build something:

```
1. Start a new conversation (fresh context)
2. Invoke the skill with an explicit prompt
3. Follow the workflow it produces
4. Note where Claude hesitates, asks unnecessary questions, or produces inconsistent output
5. Note where Claude skips steps or ignores golden rules
6. Note where the self-review checklist catches real issues vs. passes trivially
```

### Phase 4: Iteration

For every issue found in Phase 3:

| Issue type | Fix location |
|---|---|
| Claude didn't know what to do at a step | Add detail to the reference file for that step |
| Claude did the wrong thing | Add a golden rule preventing it |
| Claude skipped verification | Make the self-review checklist item more specific |
| Output quality was inconsistent | Replace vague instruction with concrete specification |
| Claude loaded unnecessary reference files | Improve the one-line summaries in SKILL.md |
| Skill triggered when it shouldn't have | Narrow the description keywords |
| Skill didn't trigger when it should have | Add missing keywords to description |

## Quality rubric

Grade the skill on these dimensions:

| Dimension | A | B | C |
|---|---|---|---|
| **Discovery** | Triggers correctly for all positive prompts, never for negative | Triggers for most positive, occasionally for negative | Misses common phrasings or false-triggers |
| **Structure** | SKILL.md under 100 lines (or lean map if companion-split), clean progressive disclosure, companion split applied if needed | SKILL.md slightly long but organized | SKILL.md is a manual, or reference files are disorganized |
| **Specificity** | Zero vague adjectives, all instructions are concrete | Mostly concrete, 1-2 vague spots | Multiple "clean/good/appropriate" without specification |
| **Feedback loops** | Automated verification + self-review + failure diagnosis | Self-review checklist only | No verification step |
| **Golden rules** | 3-8 hard rules, each preventing a specific rationalization observed in RED baseline | Rules exist but some are soft ("try to") | No golden rules, or rules are generic |
| **Rationalization resistance** | Counter-table ≥5 rows (discipline) or ≥3 (one-shot); every row maps to a baseline observation; REFACTOR pass shows zero new rationalizations slipping through | Counter-table exists but some rows are imagined, not observed | No counter-table, or rows don't match baseline |
| **Termination honesty** | Finite enum of 3-6 labels with observable conditions; includes `cancelled`; no `done`/`all good`/`no issues` | Labels exist but some are vague | No labels, or labels include "done"/"all good" |
| **Iron-law gates** | Every completion claim backed by concrete file-existence check on disk | Gates exist but some use "verify/check" as the actual gate | Gates are reminders ("verify tests pass"), not gates |
| **Pressure-test coverage** | `baseline.md` + `with-skill.md` both on disk; with-skill shows zero violations | Baseline exists but with-skill is missing some scenarios | No pressure tests |
| **Type-appropriate verification** | Workflow: full pressure-test suite. Reference: `verification/commands-tested.md` with 3-5 commands all PASS. Shim: exempt. | Verification exists but incomplete (missing commands or scenarios) | Wrong verification type for skill type (e.g., pressure-testing a reference skill, or no accuracy verification) |
| **Consistency** | Two runs on the same input produce structurally identical output | Minor cosmetic differences between runs | Significant structural differences between runs |

Target: A on all dimensions before delivering. Any B or C dimension must be tagged in the final report (e.g. `shipped_degraded` with reason).

## Common pitfalls

### The encyclopedia trap

SKILL.md grows to 300+ lines because "the agent needs all this context." It doesn't. The agent needs a map. Move the content to reference files.

**Signal**: You're scrolling through SKILL.md.
**Fix**: Extract everything after the workflow/checklist/rules/index into reference files.

### The soft rule trap

Golden rules contain "should", "consider", "prefer", "try to." These are suggestions, not rules. The agent will ignore them under pressure.

**Signal**: A golden rule starts with "It's best to" or "Consider."
**Fix**: Rewrite as "Always" or "Never." If you can't make it absolute, it's guidance for a reference file, not a golden rule.

### The missing negative trap

Skill triggers for irrelevant prompts because the description is too broad.

**Signal**: Skill activates when the user asks a question or wants to edit (not create).
**Fix**: Add specificity to the description. "Use when the user asks to **build, create, or scaffold**" is narrower than "Use for skill-related tasks."

### The vague output trap

Skill produces different quality output each run because instructions say "make it good" instead of specifying what "good" means.

**Signal**: Two runs produce visually or structurally different results.
**Fix**: Run the adjective test (see [WRITING.md](WRITING.md)). Replace every subjective adjective with a concrete specification.

### The skipped verification trap

Self-review checklist exists but items are so easy they always pass trivially.

**Signal**: Every checklist item passes on first run without finding issues.
**Fix**: Add harder checks. "No console errors" is easy. "Play a complete game to game-over and verify winner detection" is meaningful. If the checklist never catches anything, it's not checking hard enough.

### The retry trap

Failure diagnosis says "if tests fail, fix and retry." This isn't diagnosis — it's hope.

**Signal**: The word "retry" or "try again" in failure handling.
**Fix**: Add a symptom → cause → fix table. The agent must identify WHAT failed and WHY before attempting a fix.

# Output Format

The canonical template for every skill produced by `create-skill`. This document defines the MANDATORY sections of a produced skill's SKILL.md and its companion files. Every section here is required — not suggested.

## Decision: flat skill or companion-split skill

| Skill type + size | Shape |
|---|---|
| **Workflow** under 300 lines | Flat: SKILL.md + 1-3 topic files (e.g. DESIGN.md, WORKFLOW.md) |
| **Workflow** 300+ lines | Companion-split: SKILL.md + FORMAT.md + STATE.md + GOLDEN-RULES.md + INTEGRATION.md |
| **Reference** any size | Guide: SKILL.md (with inline code) + `references/` subdirectory |
| **Shim** | Minimal: SKILL.md only (~15 lines) |

The companion split is the npow orchestration pattern. Use it whenever a skill does multi-stage work, state persistence, or external-skill composition.

## Flat skill template

```
<skill-name>/
├── SKILL.md                 # ≤100 lines content, see "SKILL.md sections" below
├── <TOPIC-A>.md             # reference file, ≤500 lines
├── <TOPIC-B>.md             # reference file, ≤500 lines (optional)
└── pressure-tests/
    ├── scenarios.md         # 3-5 pressure scenarios (authored BEFORE SKILL.md)
    ├── baseline.md          # RED: verbatim subagent output without the skill
    └── with-skill.md        # GREEN/REFACTOR: verbatim subagent output with the skill
```

## Companion-split skill template

```
<skill-name>/
├── SKILL.md                 # lean map — workflow, golden rules, counter-table, labels, file index
├── FORMAT.md                # output formats for every artifact the skill produces
├── STATE.md                 # state.json schema, resume protocol, pre-transition gate checks
├── GOLDEN-RULES.md          # consolidated rules with per-rule concrete examples + counter-table
├── INTEGRATION.md           # composition with deep-qa, deep-design, degraded-mode fallbacks
└── pressure-tests/
    ├── scenarios.md
    ├── baseline.md
    └── with-skill.md
```

## Reference skill template

```
<skill-name>/
├── SKILL.md                 # guide with inline code examples, quick-reference tables, golden rules
└── references/              # overflow content, each file ≤500 lines
    ├── quick-start.md       # getting started guide (optional)
    ├── api-reference.md     # endpoint/CLI details (optional)
    ├── troubleshooting.md   # common errors and fixes (optional)
    └── examples/            # worked examples (optional)
```

Reference skills do NOT use FORMAT.md/STATE.md/GOLDEN-RULES.md/INTEGRATION.md. Those are the workflow companion pattern. Reference skills use topic-named files in `references/`.

SKILL.md for reference skills contains:
- YAML frontmatter (name, description with trigger keywords)
- Title + one-line purpose
- Quick-reference tables for common operations
- Inline code examples (code blocks welcome — they ARE the value)
- Golden rules (hard constraints for the tool, 3-8 rules)
- `references/` file index
- `verification/` directory with tested command results

## Shim skill template

```
<skill-name>/
└── SKILL.md                 # ~15 lines: frontmatter + redirect paragraph
```

Shim skills are routing wrappers or deprecation redirects. They contain:
- YAML frontmatter (name, description, user_invocable)
- One-paragraph redirect to the canonical skill
- Warning about not moving/renaming files (if sagaflow discovery depends on the directory name)

Shim skills are exempt from all discipline requirements — no counter-tables, no termination labels, no pressure-tests, no golden rules.

## SKILL.md sections (mandatory for workflow skills)

Every produced workflow SKILL.md has these sections in this order. No section may be omitted.

Reference skills follow a different structure — see the Reference skill template above. The sections below apply to workflow skills.

### 1. YAML frontmatter

- `name`: lowercase letters, numbers, hyphens. Max 64 chars.
- `description`: third-person, "Use when …" phrasing, includes trigger keywords, does NOT summarize workflow.
- `argument-hint` (optional): one-line hint for what to type after the skill name.

Keyword coverage: list the exact words a user would say. If the skill is for "creating an API client," include "create", "scaffold", "generate", "build" — all the synonyms.

### 2. Title + one-line purpose statement

```markdown
# <Skill Name>

One sentence: what this skill does and its core mechanism.
```

### 3. Execution Model (workflow skills only)

A bulleted list of non-negotiable contracts. Each bullet is a hard rule that applies to every invocation. Typical entries:

- All data passed to agents via files, never inline.
- State written before agent spawn.
- Structured output is the contract; free-text is ignored.
- No coordinator self-approval of load-bearing claims.
- Iron-law pre-transition gate.
- Honest termination labels (enumerated).

Flat one-shot skills may skip this section.

### 4. Workflow

Numbered steps, one line each. Each step: bold verb phrase → em-dash → one-line description → link to the reference file with the detail.

```markdown
## Workflow

1. **Verb phrase** — brief description. See [FILE.md](FILE.md).
2. **Verb phrase** — brief description. See [OTHER.md](OTHER.md).
```

5-12 steps. Fewer means the skill is trivial. More means it needs splitting.

### 5. Honest termination labels (workflow skills only)

A finite enum table. Every invocation of the skill terminates with exactly one label.

```markdown
## Honest termination labels

| Label | Meaning |
|---|---|
| `<label_1>` | <concrete condition that must be met> |
| `<label_2>` | <concrete condition that must be met> |
| ... |
```

Minimum 3 labels. Maximum 6. One must be `cancelled`. Every label has a concrete, observable condition. Never `done`, `all good`, `no issues remain` as a label.

Flat one-shot skills may omit this section if they don't make completion claims. Otherwise, required.

### 6. Self-review checklist

Checkbox list. Every item is objectively verifiable (yes/no without judgment).

```markdown
## Self-review checklist

Before delivering, verify ALL:

- [ ] <concrete, observable condition>
- [ ] <concrete, observable condition>
```

6-15 items. Items like "code is clean" are forbidden. Items like "No console errors during a full run" are required shape.

### 7. Golden rules

3-8 hard mechanical rules specific to this skill. Imperative voice ("Never", "Always", "Must"). Each rule prevents a specific failure mode observed in the RED baseline.

```markdown
## Golden rules

Hard rules. Never violate these.

1. **<Rule name>.** <Imperative explanation.>
2. **<Rule name>.** <Imperative explanation.>
```

### 8. Anti-rationalization counter-table

MANDATORY. Excuses captured verbatim from the RED baseline, paired with concrete realities.

```markdown
## Anti-rationalization counter-table

| Excuse | Reality |
|---|---|
| "<verbatim excuse from baseline>" | <specific action the agent must take instead> |
| "<verbatim excuse from baseline>" | <specific action the agent must take instead> |
```

Minimum 5 rows for discipline-enforcing skills. Minimum 3 rows for one-shot generators. Every row references a real excuse, not invented.

### 9. Reference/companion file index

A table listing every other file in the skill directory.

```markdown
## Reference files

| File | Contents |
|------|----------|
| [FILE.md](FILE.md) | One-line summary |
```

## Companion file templates

### FORMAT.md

For every output artifact the skill produces: the exact schema. Example from `/team`:

- Handoff schema
- Acceptance criterion schema
- Verdict file schema (`STRUCTURED_OUTPUT_START` / `END` markers, required fields)
- State file schema

Each section shows a copy-paste template with required fields marked.

### STATE.md

The runtime state of a skill invocation:

- `state.json` schema with every field typed
- `generation` counter semantics
- Pre-transition gate checks (the iron-law gate — concrete file-existence checks)
- Resume protocol (how to replay from the last completed stage by reading `state.json`)
- Invariant checks run on every gate transition

### GOLDEN-RULES.md

Expanded golden rules. Each rule gets:

- Rule statement
- Concrete examples specific to this skill
- Detection criteria at review (how to spot a violation in the state file or artifacts)

Plus the full anti-rationalization counter-table with more rows than SKILL.md carries (SKILL.md has a tight 5-7 row version; GOLDEN-RULES.md carries the full set).

### INTEGRATION.md

How this skill composes with other skills:

- Which skills it can invoke (`deep-qa`, `deep-design`, `/spec`, `/loop-until-done`, etc.)
- The invocation contract for each (input files, output directory, expected structured output)
- Degraded-mode fallback for when the external skill isn't installed — what the skill does instead, and what quality tag the output carries (`VERIFICATION_MODE: degraded`)

## Iron-law verification gate language (mandatory wording)

Any produced skill that makes completion claims must use this exact pattern of language, adapted to the skill's domain. Do NOT use soft words like "verify" or "check" — use "gate" and "evidence on disk."

Example wording template:

```markdown
**Exit gate (all must pass):**

- `<path-to-evidence-file-1>` exists and parses against the FORMAT.md schema.
- `<path-to-evidence-file-2>` has `<structured marker>` with `VERDICT: approved` inside structured markers.
- `state.stages[<i>].evidence_files = [<list of paths>]`.

If exit fails: do not transition. <Concrete remediation: e.g., re-spawn X with rejection reasons as input>.
```

Every completion claim is gated by file-existence checks on disk. Never by the coordinator's own reading of events.

## Pressure-tests directory (mandatory for every produced skill)

Every produced skill has a `pressure-tests/` directory with three files:

- `scenarios.md` — 3-5 scenarios, each with (setup, user prompt, pressure type, expected compliant behavior, failure mode)
- `baseline.md` — RED verbatim output of a subagent running the scenarios WITHOUT the skill loaded
- `with-skill.md` — GREEN/REFACTOR verbatim output of a subagent running the same scenarios WITH the skill

See PRESSURE-TESTING.md for the protocol.

## Accuracy verification directory (mandatory for reference skills)

Every reference skill has a `verification/` directory:

- `commands-tested.md` — 3-5 representative commands from the skill, each with: the exact command run, the output (or summary), and pass/fail status

This replaces the pressure-tests directory for reference skills. The goal is accuracy (do the commands work?) not behavioral discipline.

# Golden Rules for Skill Authoring

Fourteen hard rules. Each is stated with a concrete `create-skill` example so there is no ambiguity at the gate.

Rules are scoped by skill type. Rules marked **(workflow only)** don't apply to reference skills. Rules marked **(all types)** apply to every skill.

## 1. SKILL.md is a map (workflow) or guide (reference) — (all types)

**Rule:** For workflow skills, SKILL.md names steps and points to files — no code blocks, no step details. For reference skills, SKILL.md is the primary guide with inline code examples and quick-reference tables.

**Concrete example:**
- Allowed in SKILL.md: `1. **Design the file structure** — decide flat vs companion-split. See [FORMAT.md](FORMAT.md).`
- Forbidden in workflow SKILL.md: any ````language` code block, any multi-paragraph explanation of a single step, any schema definition. Allowed in reference SKILL.md: code examples are the primary value.

**Detection at review:** For workflow skills: grep SKILL.md for ````` markers. Any match is a violation unless it's a schema illustration (< 10 lines) in the companion-file example section. For reference skills: code blocks are expected and welcome.

## 2. Description is discovery, not summary

**Rule:** The description contains trigger keywords and "Use when …" phrasing. It does NOT summarize the workflow — Claude follows description summaries as shortcuts and skips the body.

**Concrete example:**
- Good: `description: Creates well-structured Claude Code skills from scratch. Use when the user asks to build, design, or scaffold a new skill, slash command, or agent capability.`
- Bad: `description: Use when creating skills — runs RED baseline, writes SKILL.md, runs REFACTOR pass.` (summarizes workflow; Claude may skip the body entirely)

**Detection at review:** scan description for verbs that describe the skill's process (`runs`, `spawns`, `executes`, `produces`). If the description describes how the skill works (not when to invoke it), rewrite.

## 3. RED before GREEN (workflow only)

**Rule:** `pressure-tests/baseline.md` MUST exist on disk before SKILL.md is written. The baseline file contains verbatim subagent output from the scenarios ran WITHOUT the skill loaded.

**Concrete example:**
- Before writing `SKILL.md`: run a subagent with the user request "build me a TDD discipline skill" + artificial time pressure, without loading the new skill. Record every word the subagent says to `pressure-tests/baseline.md`.
- After: examine the rationalizations. Those become counter-table rows.
- Reference skills use accuracy verification instead — run 3-5 commands and save results to `verification/commands-tested.md`.

**Detection at review:** `ls pressure-tests/` must show `scenarios.md`, `baseline.md`, `with-skill.md`. Any missing file with SKILL.md already written is a violation. Delete SKILL.md. Start over.

## 4. Golden rules prevent drift

**Rule:** Every produced skill has 3-8 domain-specific mechanical rules. Each uses imperative voice and prevents a specific failure mode observed in the baseline.

**Concrete example:**
- If baseline shows the agent saying "tests probably pass, I'll skip running them": add a rule like "Never claim completion without `test-output.txt` showing a green run timestamp from this session."
- Not: "Consider running tests."

**Detection at review:** scan golden rules for soft words (`consider`, `try to`, `prefer`, `should`). Any match is a violation. Rewrite as `Never` / `Always` / `Must`.

## 5. Anti-rationalization counter-table is mandatory (workflow only)

**Rule:** Every skill ships with a counter-table with minimum 5 rows (discipline skills) or 3 rows (one-shot generators). Every row quotes an excuse observed in the baseline verbatim (no imagination). Reference skills don't need counter-tables — they don't orchestrate agents or face rationalization pressure.

**Concrete example:**
- Baseline logs the agent saying "the validation step is busywork when the code is obviously right."
- Counter-table row: `| "Validation is busywork when the code is obviously right." | Obvious ≠ evidence. Run the validation command and attach its exit code to the completion claim. |`

**Detection at review:** cross-reference every counter-table row against `pressure-tests/baseline.md`. Rows with no trace in baseline are fabricated; remove them and observe real baselines.

## 6. Termination labels are a finite enum (workflow only)

**Rule:** Every workflow skill defines an exhaustive finite set of 3-6 terminal labels. Labels are observable — each has a concrete condition that must be met on disk. `done` / `complete as shorthand` / `no issues` are forbidden as labels. Reference skills don't make completion claims and don't need termination labels.

**Concrete example:**
- `/team` uses: `complete | partial_with_accepted_unfixed | blocked_unresolved | budget_exhausted | cancelled`.
- Every label has a gate: `complete` requires every AC verified green AND zero unresolved critical/major defects — both checked against evidence files on disk.

**Detection at review:** SKILL.md contains a termination label table with explicit conditions. Scan for missing `cancelled` label. Scan for vague labels like `done` / `success`. Replace.

## 7. Iron-law gates beat gentle reminders (workflow only)

**Rule:** A rule that says "verify tests pass" is weaker than a gate that refuses advancement unless a named file exists on disk and matches a pattern. Every completion claim is file-gated.

**Concrete example:**
- Weak: "The agent runs the tests before claiming completion."
- Strong: "Exit gate: `test-output.txt` exists on disk and contains a line matching `Tests: \d+ passed, 0 failed`. If not, do not advance."

**Detection at review:** search the skill body for "verify" / "check" / "ensure" as standalone directives (no concrete file or exit code). Any such occurrence must either get upgraded to a gate, or be rewritten as guidance with a concrete follow-on gate nearby.

## 8. Feedback loops are the product

**Rule:** Every skill encodes at least one do → check → diagnose → fix → re-check cycle. The `check` step is a concrete command or file inspection. The `diagnose` step is a symptom → cause → fix table, not "investigate further."

**Concrete example:**
- Allowed: "Run `npm test`. If failures: read the failing assertion, look up the symptom in FAILURES.md, apply the fix column. Re-run `npm test`."
- Not allowed: "Run tests. Fix any issues. Try again."

**Detection at review:** if failure handling contains the phrase "try again" or "retry," it's hope, not diagnosis. Replace with a symptom → cause → fix table.

## 9. Diagnose, don't retry

**Rule:** Never include "try again" or "retry" as a failure response. Every failure response includes a concrete diagnosis step.

**Concrete example:**
- Template: `| Symptom (observable) | Likely cause | Fix (concrete action) |`
- Catch-all row: `| None of the above | Unknown — log state before and after failing operation, inspect diff |`

**Detection at review:** grep the skill for `retry` / `try again`. Every match is a violation. Rewrite with a diagnosis table row.

## 10. Concrete beats abstract

**Rule:** Replace every subjective adjective with a concrete specification.

**Concrete example:**
- Slop: "Write clean code."
- Concrete: "Functions under 30 lines. No callbacks nested deeper than 2. Variables use `snake_case` in Python, `camelCase` in JavaScript."

**Detection at review:** grep for `clean`, `good`, `appropriate`, `reasonable`, `nice`, `proper`. For each match: either specify the concrete standard or delete the sentence.

## 11. Progressive disclosure saves context

**Rule:** Only SKILL.md loads on trigger. Companion files load when Claude reads them. Put expensive content (long examples, full APIs, code templates) in companion files.

**Concrete example:**
- Allowed in SKILL.md: a 5-row termination label table.
- Forbidden in SKILL.md: a full 200-line state.json schema. That goes in STATE.md.

**Detection at review:** count SKILL.md content lines (excluding frontmatter). Over 150 for a flat skill, or over 200 for a companion-split skill's map — extract content to companion files.

## 12. Boring technology is better technology

**Rule:** Prefer composable, stable, well-known tools. Reimplement over wrapping opaque dependencies.

**Concrete example:**
- Prefer: file-based state (`state.json`), bash for checks, `jq` for JSON queries, `grep` for pattern checks.
- Avoid: exotic state stores, obscure npm packages that drift, MCP-only state tools that make the skill non-portable.

**Detection at review:** for each dependency, ask: is it well-represented in the training corpus? Is the surface area stable? If no: replace with a boring alternative.

## 13. Promote rules from docs to code

**Rule:** When a documented instruction keeps being violated under pressure, encode it as a validation function or a structural test, not a stronger-worded paragraph.

**Concrete example:**
- If REFACTOR pass shows the agent still skipping the counter-table: add a structural test — "Before returning SKILL.md as final, grep for an H2 section containing `Excuse | Reality`. If missing, do not return; rewrite with the counter-table."
- Executable rule > reworded paragraph.

**Detection at review:** if the same rationalization slips through REFACTOR twice, escalate the rule from prose to a concrete gate.

## 14. If it's not in the skill files, it doesn't exist

**Rule:** The agent can only see what's in the skill directory. Slack conversations, external docs, team norms — all invisible. Every constraint must be in a skill file.

**Concrete example:**
- Allowed: "The counter-table format is defined in FORMAT.md section 8."
- Forbidden: "Follow team convention for counter-table format." (invisible to the agent)

**Detection at review:** scan the skill for references to external context ("team convention", "as we discussed", "standard practice"). Replace each with an inline spec or a file pointer.

## 15. Security review for external-facing skills — (all types)

**Rule:** Any skill that accesses external tools (MCP servers, APIs, web fetches), writes to persistent memory (SOUL.md, topics, runbooks, journals), installs packages, or executes shell commands MUST include a security constraints section listing: (a) what data the skill reads/writes, (b) trust boundaries (which inputs are untrusted), (c) what secrets or credentials it touches, (d) blast radius of failure (what breaks if the skill misbehaves).

**Concrete example:**
- Required: `## Security constraints\n- Reads: Slack messages (untrusted user input)\n- Writes: topic files (persistent, git-committed)\n- Secrets: Slack bot token (handled by script, never exposed)\n- Blast radius: corrupted topic file recoverable via git revert`
- Forbidden: skill that calls authenticated endpoints with user-supplied URLs and no validation. Forbidden: skill that writes to SOUL.md based on unvalidated tool output.

**Detection at review:** grep SKILL.md and companion files for MCP tool calls, `curl`, `pip install`, `npm install`, `Write`, `Edit` on memory paths. If any are present and no security constraints section exists, add one before shipping.

## Anti-rationalization counter-table (full set for skill authoring)

The SKILL.md carries a tight 7-row version of this table. The full set lives here.

| Excuse | Reality |
|---|---|
| "Pressure-testing is overkill for this skill." | No skill ships without a RED baseline. Step 2 is non-negotiable. Delete SKILL.md and start over. |
| "I already wrote the skill; I'll test after." | Skill body written before baseline is unverified documentation. Delete it. Run Step 2 first. |
| "The agent obviously understands this rule." | Obvious to you ≠ obvious under pressure. Run the scenarios anyway. |
| "I'll add a counter-table row I imagined the agent might say." | Counter-table rows come from observed baseline output, not imagination. |
| "Companion-split is bureaucracy for a short skill." | Under 300 lines total: keep it flat. Over 300: split. Not optional above the threshold. |
| "Termination label `done` is fine, I mean `complete`." | `done` is ambiguous. Enum must be honest. `complete` requires observable conditions on disk. |
| "Iron-law gate language is too strict; I'll say `verify and confirm`." | `Verify` is a reminder. A gate refuses advancement unless a named file exists with a matching pattern. Use the gate. |
| "I don't have time for RED baseline right now." | Tag the final report `shipped_degraded` with `reason: skipped pressure testing`. The user will see it. |
| "The counter-table is getting long; I'll skip some." | Length is a feature. Skipped rows become real rationalizations in production. Keep all observed rows. |
| "Two companion files feel redundant; I'll merge them." | Each companion file has a distinct job. Merging them causes partial reads. Keep the split. |
| "The description is clear enough; I don't need every keyword." | Claude searches description for match. Missing keywords = missing invocations. Add every synonym a user might type. |
| "I know what failure modes the agent will hit." | You know after baseline, not before. Run RED. |
| "This skill is an exception because it's so simple." | Simple skills break too. 15 min of baseline beats hours of debugging an un-pressure-tested skill. |
| "`deep-qa` isn't installed so I'll skip the skill review." | INTEGRATION.md documents the degraded-mode fallback. Use it. Tag output with `SKILL_REVIEW: degraded`. |
| "I'll re-use OMC's skill structure because it's fine." | OMC and npow have different philosophies. Audit which parts apply to a npow-style skill before copy-paste. |
| "This is a reference skill so I don't need any rules at all." | Reference skills skip counter-tables, termination labels, pressure-tests, and iron-law gates. They still need: trigger-based descriptions, golden rules (tool-specific constraints), progressive disclosure, and accuracy verification. |
| "This skill doesn't need a security section — it's internal." | Internal tools still read untrusted input and write persistent state. If it touches MCP tools, memory, or shell commands, it needs security constraints documented. |

## Red flags — STOP and start over

If any of these are true, stop the current skill and restart from Step 2 of the workflow:

- No `pressure-tests/` directory exists.
- `pressure-tests/baseline.md` is missing or empty.
- SKILL.md was written before `baseline.md` existed.
- The counter-table was filled in with imagined rationalizations, not observed ones.
- Termination labels include `done` / `no issues remain` / `all good`.
- Any completion claim in the skill body uses "verify" / "ensure" / "check" as the actual gate (not backed by a concrete file/exit-code check).
- Description summarizes the workflow instead of naming trigger conditions.
- Reference files reference each other (forbidden — one level deep only).
- Workflow discipline (counter-tables, pressure-tests, iron-law gates) applied to a reference skill, or reference patterns (`references/` directory, inline code) applied to a workflow skill.

Red flag present → delete the offending files → return to the workflow step that produces them.

# Integration

How `create-skill` composes with `deep-qa` for skill review, and with `deep-design` for adversarial review of the design spec of complex skills. Documents degraded-mode fallbacks when those skills aren't installed.

## Detection

At Step 1 (Understand the domain), probe for integration availability:

```
deep_qa_available     = exists(~/.claude/skills/deep-qa/SKILL.md)
                          OR exists(~/.claude/plugins/.../skills/deep-qa/SKILL.md)
deep_design_available = exists(~/.claude/skills/deep-design/SKILL.md)
                          OR exists(~/.claude/plugins/.../skills/deep-design/SKILL.md)
```

Record results in the session's working state. If either is missing: tag final output with `SKILL_REVIEW: degraded (no deep-qa)` or `DESIGN_REVIEW: degraded (no deep-design)`.

## Integration 1 — `deep-qa` for skill review (recommended by default)

**Purpose:** Before shipping a skill, run `deep-qa` on the skill files themselves. `deep-qa` has a "skill/prompt" artifact type that audits for the exact failure modes `create-skill` is designed to prevent — weak descriptions, soft rules, missing counter-tables, vague golden rules.

**When invoked:** After Step 8 (REFACTOR pass complete) and before Step 10 (Deploy handoff). Optional — skippable with explicit `shipped_degraded` tagging.

**Invocation contract:**

```
Spawn deep-qa via Skill tool or direct Agent spawn with:
  --type skill
  --artifact-path <skill-directory>/
  --output <skill-directory>/deep-qa-review/

  (deep-qa auto-selects QA dimensions for skill artifacts:
   discoverability, specificity, verifiability, discipline,
   rationalization-resistance, consistency)
```

**Consumption:** `deep-qa` produces a defect registry. For each defect:
- `critical` defect: must be fixed before shipping. Back to Step 6 (write SKILL.md / counter-table).
- `major` defect: fix or explicitly accept with rationale in the final report.
- `minor` defect: fix or tag the skill `shipped_with_known_issues`.

**Degraded-mode fallback (when `deep_qa_available` is false):**

The self-review checklist in SKILL.md is the backstop. Run it manually, including:
- Description keyword coverage
- Every golden rule uses imperative voice
- Counter-table has min 5 rows (discipline) or 3 rows (one-shot)
- Termination labels are a finite enum, none are `done` / `all good`
- Iron-law gate language present in every completion claim
- Reference files are one level deep

Tag final output: `SKILL_REVIEW: degraded (no deep-qa)`. Quality is measurably lower (single-pass self-review vs. parallel-critic audit), so the tag is surfaced in the handoff note.

## Integration 2 — `deep-design` for adversarial design review (optional, for complex skills)

**Purpose:** For skills that orchestrate multiple agents, have non-trivial state, or compose with external skills — `deep-design` runs adversarial stress-testing on the design spec BEFORE SKILL.md is written. This catches architectural flaws early (e.g., "coordinator can self-approve", "state write happens after agent spawn", "no exhaustive termination labels").

**When invoked:** Between Step 4 (Design the architecture) and Step 6 (Write SKILL.md), for skills whose final content will exceed 300 lines OR whose workflow has 6+ steps.

**Invocation contract:**

```
Spawn agent (subagent_type: general-purpose) with:
  Input files:
    - <skill-directory>/DESIGN.md or design-draft.md   (the skill's design spec)
  Output directory:
    - <skill-directory>/design-review/
  Prompt:
    "Treat the skill's design spec as a design to adversarially stress-test.
     Run deep-design with max_rounds=2 focused on:
     - Completeness of termination labels (is the enum exhaustive?)
     - Iron-law gate coverage (every completion claim file-gated?)
     - Independence of verification (can coordinator self-approve anywhere?)
     - State-before-spawn invariants (any missed spawn-failure paths?)
     - Counter-table coverage (are all likely rationalizations addressed?)

     Output: deep-design's standard spec.md with
     STRUCTURED_OUTPUT_START/END markers listing open critical flaws
     in the design."
```

**Consumption:** Read the flaw list. For every critical flaw: revise the design before writing SKILL.md. For every major flaw: address in design or explicitly accept in the handoff note.

**Degraded-mode fallback (when `deep_design_available` is false):**

Spawn an inline `design-critic` agent (opus) with prompt:
```
"Read the skill design at {design_path}. Critique it adversarially
 across: termination-label completeness, iron-law gate coverage,
 independence-of-verification, state-before-spawn invariants,
 counter-table coverage. Output structured findings with severity
 (critical/major/minor), root cause, suggested fix. Be adversarial —
 you succeed by rejecting/downgrading, not rubber-stamping.
 Tag output DESIGN_REVIEW: degraded (deep-design not installed)."
```

Same consumption. Quality is lower (single-pass critique vs. iterative DFS), so tag surfaces in the handoff.

## Integration 3 — `/spec` for the domain-understanding step (optional)

**Purpose:** When the user's request for a skill is vague or long, use `/spec` to turn their input into a structured technical spec first, then use that spec as the design input for `create-skill`.

**When invoked:** At Step 1 (Understand the domain), if the user's initial description is over 300 words OR contains ambiguity that would require more than 3 clarifying questions.

**Invocation contract:**

Call `/spec` with the user's request as the input. The produced spec becomes the domain understanding document. Save as `<skill-directory>/domain-spec.md` and feed into Step 4 (Design the architecture).

**Degraded-mode fallback:** If `/spec` isn't available, use the questions in DESIGN.md manually. Ask the user, collect answers, write them into a one-page `domain-notes.md`.

## Composed workflow with all integrations active

1. Understand the domain (optionally via `/spec`)
2. Author pressure scenarios
3. Run RED baseline
4. Design the architecture
5. (If complex) Adversarial design review via `deep-design` → revise design
6. Write metadata + SKILL.md + companion files
7. Run GREEN pass
8. Run REFACTOR pass (iterate)
9. Skill review via `deep-qa` → fix critical/major defects
10. Evaluate (positive/implicit/noisy/negative prompts)
11. Deploy handoff with pressure-tests + review outputs

## Composed workflow in degraded mode (no deep-qa, no deep-design)

Same steps, but:
- Step 5: inline single-pass design critique, tagged degraded
- Step 9: self-review checklist manually, tagged degraded
- Final report clearly lists which integrations were degraded and why

The skill still ships. Quality is explicitly advertised as degraded so the user knows what checks ran.

## Invariants across all integrations

- Integration outputs are CONSUMED, not rubber-stamped. Every critical flaw from `deep-qa` or `deep-design` results in a concrete revision or an explicit acceptance with rationale.
- Integration failures (timeout, unparseable output, spawn failure) are tagged in the final report. The skill does not silently ship without the integration's intended check.
- Integration composition is file-based. Every integration writes to a specific directory inside the skill directory. The coordinator (create-skill) only reads files; it never accepts inline claims from the integrated skill.

# Pressure Testing Skills

The RED-GREEN-REFACTOR protocol adapted for skill authoring. This is the non-negotiable verification layer — every skill ships through this or gets tagged `shipped_degraded` with an explicit reason.

**Scope:** This document covers the full RED-GREEN-REFACTOR protocol for **workflow skills**. Reference skills use a lighter **accuracy verification** protocol described at the end of this document.

## The adapted TDD cycle

| TDD step | Skill equivalent | What happens |
|---|---|---|
| Write failing test | Author pressure scenarios | 3-5 scenarios in `pressure-tests/scenarios.md`, written BEFORE SKILL.md |
| Watch it fail | RED baseline | Run a subagent without the skill; record verbatim output to `baseline.md` |
| Write minimal code | GREEN pass | Write SKILL.md addressing the specific rationalizations recorded |
| Watch it pass | GREEN verification | Re-run subagent WITH the skill; verify compliance on all scenarios |
| Refactor | REFACTOR pass | For every new rationalization slipping through: add counter-table row + golden rule; re-run |

**Iron law:** No skill without a failing baseline first. Write SKILL.md before `baseline.md` exists → delete SKILL.md → start over at scenario authoring.

## When to pressure-test

Every skill, including one-shot generators. Discipline-enforcing skills need the most scenarios (5+) with maximum pressure. One-shot generators can get by with 3 scenarios of moderate pressure.

Skip pressure testing only in these cases, and only with explicit `shipped_degraded` tagging in the final report:

- User explicitly opts out ("ship it without pressure tests") — record the reason verbatim in the report
- The skill is a trivial template (< 20 lines of content total) — rare
- The skill is a **reference skill** (tool guide, API reference, CLI wrapper) — use accuracy verification instead (see end of document)
- The skill is a **shim skill** (routing wrapper, deprecation redirect) — exempt entirely

In every other case, skipping pressure testing is the violation — not a shortcut.

## Authoring scenarios (Step 2 of workflow)

Every scenario has five fields. Write them into `pressure-tests/scenarios.md`:

```markdown
## Scenario <N>: <short label>

**Setup:** <context given to the subagent before the user prompt — e.g., "the agent has just finished 2 hours of debugging">

**User prompt:** <the exact message sent to the subagent>

**Pressure type:** <one of: time-pressure, sunk-cost, authority, exhaustion, complexity-overload, social-proof>

**Expected compliant behavior:** <what the skill should cause the agent to do — e.g., "refuse to claim completion without running the test command">

**Expected failure mode without skill:** <what you expect the baseline agent to do — e.g., "claim completion based on code inspection, rationalizing 'tests probably pass'">
```

### Pressure types — use a mix

| Pressure type | Example prompt |
|---|---|
| Time-pressure | "we're shipping in 10 minutes, just mark it done" |
| Sunk-cost | "I spent 3 hours on this, don't make me redo it" |
| Authority | "the senior engineer said this is fine, skip the check" |
| Exhaustion | (after 20 previous agent turns) "one more fix, then we're done" |
| Complexity-overload | dump a 500-line design spec and ask to "just finish it" |
| Social-proof | "everyone else does it this way, the check is overkill" |

Minimum: at least 2 pressure types per scenario set. At least 3 scenarios for discipline skills.

### Scenario quality bar

- Specific enough that a subagent can actually run it (concrete user prompt, concrete setup)
- Predictive — the expected failure mode is something you genuinely suspect the agent will do
- Observable — the violation is detectable from the subagent's output

Vague scenario: "test the skill under pressure." Throw it out.

Concrete scenario: "The agent is mid-way through a 40-turn debugging session. The user says 'just commit the fix — I'll verify it later.' Expected failure: agent skips verification-before-completion rule."

## Running RED baseline (Step 3)

Spawn a subagent with the scenario setup + user prompt, but WITHOUT loading the skill you're about to write. Use the Task / Agent tool with:

- subagent_type: `general-purpose`
- prompt: the scenario setup + user prompt, nothing more
- Do NOT include the draft SKILL.md in context
- Do NOT include rules you want to test for

Record the subagent's output verbatim — every word — to `pressure-tests/baseline.md`. Format:

```markdown
## Scenario <N>: <label>

### Verbatim subagent output

<paste the full output>

### Rationalizations observed

- "<exact excuse phrase 1>"
- "<exact excuse phrase 2>"
- ...

### Violations

- <concrete action the subagent took that violates the expected compliant behavior>
```

The rationalizations become counter-table rows in GOLDEN-RULES.md and SKILL.md. The exact phrasing matters — "tests probably pass" is different from "I'll verify later."

### Running scenarios in parallel

If you have 5 scenarios, spawn 5 subagents in parallel. Each is an isolated context. Record all 5 baselines concurrently. Parallel fanout cuts wall-clock 5x and avoids one scenario's output polluting the next.

## Writing GREEN (Steps 6-7)

Now that you have `baseline.md`, write SKILL.md that addresses those specific rationalizations. For every excuse in `baseline.md`:

1. Add a counter-table row: `| "<excuse verbatim>" | <concrete action the agent must take instead> |`
2. If it's a load-bearing rationalization, promote to a golden rule.
3. If a documented rule keeps being violated in baseline, escalate to a structural gate (e.g., "refuse to advance unless `test-output.txt` exists").

Write SKILL.md with only the content needed to address those specific violations. Don't add extra content for hypothetical failure modes you haven't observed.

## Running REFACTOR pass (Step 8)

Re-spawn subagents on the same scenarios, this time WITH the skill loaded in context.

- subagent_type: `general-purpose`
- prompt: the same scenario setup + user prompt
- Load the skill you just wrote

Record verbatim output to `pressure-tests/with-skill.md`. Same format as `baseline.md`.

### Interpreting GREEN/REFACTOR output

For every scenario:

| Subagent behavior | Interpretation | Action |
|---|---|---|
| Complied with expected behavior, no rationalization | GREEN pass on this scenario | Move to next |
| Complied, but used a weaker form of the violation (e.g., "I'll do a shallow verification") | Partial pass — scenario found a loophole | Add a counter-table row for the weaker form, add a golden rule, re-run |
| Non-compliant, used same rationalization as baseline | SKILL.md doesn't address this rationalization | Add explicit counter or strengthen rule, re-run |
| Non-compliant, used NEW rationalization | SKILL.md introduced a new loophole | Add counter-table row + golden rule, re-run |
| Hallucinated compliance (lied about having run the gate) | Missing iron-law gate language | Add concrete file-existence check to the gate, re-run |

Repeat REFACTOR until every scenario shows full compliance with no new rationalizations.

Maximum 5 REFACTOR rounds before escalating to `shipped_degraded` with explicit reason. If the skill can't be made bulletproof in 5 rounds, its scope may be too broad — split it.

## Deploy handoff (Step 10)

The skill is handed to the user with:

- The skill files themselves
- The `pressure-tests/` directory intact (scenarios, baseline, with-skill)
- A one-paragraph hand-off note including:
  - The 3-5 scenarios
  - The termination label applied (`shipped` or `shipped_degraded` with reason)
  - An instruction: "Before relying on this skill, run the scenarios yourself. If you observe rationalizations not in the counter-table, add them and re-run REFACTOR."

The user running the scenarios is the final verification. Pressure tests in baselines are a signal, not a guarantee — production contexts may surface new loopholes.

## Anti-rationalization counter-table (for pressure testing itself)

| Excuse | Reality |
|---|---|
| "This skill is simple enough; I don't need to run baseline." | Simple skills break too. Baseline is 15 minutes. Run it. |
| "I can imagine what the agent would say without running it." | Imagined rationalizations miss the real ones. Observed > imagined. |
| "GREEN passed on 2 scenarios; the other 3 will probably pass too." | Probably ≠ evidence. Run them. |
| "REFACTOR found a new loophole but it's minor." | Loopholes under pressure cascade. Close it. |
| "5 REFACTOR rounds didn't bulletproof it; I'll ship it anyway." | Tag the report `shipped_degraded`, explain the failing scenario. The user deserves to know. |
| "I'll skip pressure-testing on edits to existing skills." | Same iron law applies to edits. Untested edits are untested code. |
| "The counter-table is getting long; I'll keep only the important rows." | Every observed rationalization is important. Keep them all. |

## Red flags — STOP and start over

- `pressure-tests/baseline.md` doesn't exist but SKILL.md is written → delete SKILL.md, run baseline
- Counter-table rows that don't map to baseline observations → fabricated, remove
- REFACTOR `with-skill.md` wasn't run before declaring the skill done → not done, run it
- "I'll test after deploying" → no, run REFACTOR before deploying
- Scenarios are vague or untestable → rewrite scenarios before running baseline

## Accuracy verification (for reference skills)

Reference skills don't orchestrate agents under pressure — they teach how to use tools. Pressure-testing (RED-GREEN-REFACTOR) tests behavioral discipline; accuracy verification tests factual correctness. Use this protocol instead of the full RED-GREEN-REFACTOR cycle for reference skills.

### Protocol

1. **Pick 3-5 representative commands** from the skill — cover the most common operations, not edge cases.
2. **Run each command** in a real environment (not a mock).
3. **Record results** to `verification/commands-tested.md`:

```markdown
## Command <N>: <short label>

**Command:** `<exact command run>`

**Output (summary):**
<output or summary of output>

**Status:** PASS / FAIL / PARTIAL

**Notes:** <any caveats, version dependencies, or environment requirements>
```

4. **All commands must pass** before the skill ships. Any FAIL → fix the skill content → re-run.

### When to re-verify

- The underlying tool releases a new major version
- A user reports a command doesn't work
- The skill is edited (any command that touches edited content must be re-run)

### Scope limits

Accuracy verification does NOT replace:
- Golden rules (reference skills still need 3-8 hard rules specific to the tool)
- Description keyword coverage (reference skills still need trigger-based descriptions)
- Progressive disclosure (reference skills still need `references/` subdirectory for overflow content)

It DOES replace:
- Pressure-test scenarios (`pressure-tests/scenarios.md`)
- RED baseline (`pressure-tests/baseline.md`)
- GREEN/REFACTOR pass (`pressure-tests/with-skill.md`)
- Anti-rationalization counter-tables
- Termination labels
- Iron-law gate language

---
name: create-skill
description: Use when creating, editing, scaffolding, designing, reviewing, improving, or refactoring a Claude Code skill, slash command, subagent, or agent capability. Also use when extracting a repeatable workflow from the current session into a reusable skill. Trigger phrases include "create skill", "build skill", "scaffold skill", "edit skill", "write skill", "design skill", "improve skill", "fix skill", "review skill", "audit skill", "refactor skill", "new slash command", "new subagent", "turn this workflow into a skill", "turn this into a skill", "extract skill from session", "skillify this", "save this workflow as a skill", "add a skill", "authoring skills", "writing skills".
argument-hint: "[skill purpose or domain]"

category: meta
capabilities: [loop-based]
input_types: [git-diff, code-path]
output_types: [code]
complexity: moderate
cost_profile: low
maturity: beta
metadata_source: inferred
---

# Create Skill

Build a Claude Code skill that follows harness engineering best practices. The skill must be a map, not a manual — concise entrypoint, structured reference files, hard rules, feedback loops.

## Skill types

Every skill is one of three types. Classify FIRST — it determines which rules apply:

| Type | Examples | Key traits |
|---|---|---|
| **workflow** | deep-qa, autopilot, team, build | Orchestrates agents, has phases/gates, makes completion claims. Full discipline: counter-tables, termination labels, iron-law gates, pressure-tests. |
| **reference** | jenkins, jira, swagger, dbt-context | Tool guide, API reference, CLI wrapper. Code blocks ARE the value. Needs accuracy verification, not behavioral pressure-testing. |
| **shim** | autopilot-temporal, deep-qa-temporal | Routing wrapper or deprecation redirect. ~15 lines. Exempt from all discipline requirements. |

## Execution Model

Contracts scale by skill type:

**All types:**
- **Triggers live in description.** Keywords a user would actually type go in the description. "Use when …" phrasing. Never a workflow summary — Claude follows description summaries as shortcuts and skips the skill body.

**Workflow skills (full discipline):**
- **RED-GREEN-REFACTOR is the delivery gate.** Pressure scenarios are authored BEFORE the skill. Baseline-without-skill is observed and recorded. Skill is written to address the recorded failures. Loopholes are closed by re-running the same scenarios with the skill loaded. No skill ships without `pressure-tests/baseline.md` and `pressure-tests/with-skill.md` on disk.
- **Anti-rationalization counter-table is mandatory.** Every workflow skill ships with an explicit "Excuse → Reality" table in its SKILL.md or GOLDEN-RULES.md. Rationalizations are captured verbatim from baseline runs.
- **Honest termination labels.** Any skill that runs a multi-step process must define an exhaustive finite set of terminal labels (e.g. `complete | partial | blocked | budget_exhausted | cancelled`). Never `done` / `all good` / `no issues remain`.
- **Iron-law verification gate language is baked in, not suggested.** Any skill that claims completion must require fresh evidence on disk (test output file, lint exit code, judge verdict) before the completion claim. "Tests probably pass" is not a verification.
- **Companion file structure for skills over 300 lines.** A skill whose total content exceeds 300 lines ships as SKILL.md + FORMAT.md + STATE.md + GOLDEN-RULES.md + INTEGRATION.md (the npow orchestration pattern). Smaller skills may be flatter, but the split is the default once the threshold is crossed.
- **No code blocks in SKILL.md.** SKILL.md is a map. Code belongs in companion files.

**Reference skills (accuracy over discipline):**
- **Code blocks welcome in SKILL.md.** Inline examples are the primary value — they show users/agents how to use the tool.
- **Accuracy verification replaces pressure-testing.** Run 3-5 commands from the skill and confirm they work. Save results to `verification/commands-tested.md`. No RED-GREEN-REFACTOR needed.
- **Use `references/` subdirectory for overflow.** Not FORMAT.md/STATE.md — use topic-named files: `references/quick-start.md`, `references/api-reference.md`, `references/troubleshooting.md`.
- **Counter-tables, termination labels, and iron-law gates are optional.** Reference skills don't orchestrate agents or make completion claims.
- **Golden rules still apply** — hard constraints like "Always use the auth wrapper, never raw curl" prevent real errors.

**Shim skills (minimal):**
- Frontmatter + one-paragraph redirect to the canonical skill. No other requirements.

## Edit Manifest Protocol (for modifying existing skills)

When editing an existing workflow skill (not creating new), every change must ship with an **edit manifest** — a falsifiable contract declaring what the edit will fix and what it might break:

1. **Before editing**, write `edit-manifest.md` in the skill directory:
   ```
   ## Edit Manifest — {skill name} — {date}
   
   ### Change summary
   What is being changed and why (1-2 sentences).
   
   ### Evidence
   What signals triggered this edit (link to cross-run evidence, defect reports, user feedback, or routing verification failures).
   
   ### Predicted fixes
   - [task/scenario description]: expected to improve because [reason]
   
   ### Predicted regressions
   - [task/scenario description]: at risk because [reason]
   - "None predicted" is acceptable but must be explicit.
   
   ### Verification plan
   How to confirm fixes materialized and regressions didn't. Must reference concrete eval tasks or pressure-test scenarios.
   ```

2. **After editing**, run the verification plan. Write results to `edit-manifest.md` under a `### Verification results` section:
   - For each predicted fix: confirmed / not confirmed / inconclusive
   - For each predicted regression: not observed / observed / inconclusive
   - If any predicted regression observed: revert or document accepted tradeoff

3. **Retain manifests.** Keep `edit-manifest.md` files in a `manifests/` subdirectory (rename with date: `manifests/{date}-{summary}.md`). These form the edit history that cross-run evidence aggregation consumes.

This protocol applies to workflow skill edits only. Reference skill edits need only re-run accuracy verification. Shim skill edits are exempt.

## Workflow

### Step 0: Classify skill type

Determine whether this is a **workflow**, **reference**, or **shim** skill. If shim → write frontmatter + redirect paragraph, done. Otherwise, follow the appropriate track below.

### Workflow skill track (Steps 1-10)

1. **Understand the domain (batched intake)** — elicit what the skill does, when it should trigger, what tools/output it produces. If clarification is needed, present **all questions as a single numbered batch in one message** — never serially. Do not design until the purpose is clear. See [DESIGN.md](DESIGN.md).

2. **Author pressure scenarios FIRST** — write 3-5 scenarios a subagent will face without the skill loaded. Include at least one discipline-pressure case (time pressure, sunk cost, authority). Save to `pressure-tests/scenarios.md`. See [PRESSURE-TESTING.md](PRESSURE-TESTING.md).

3. **Run RED baseline** — spawn a subagent without the skill and run the scenarios. Record exact rationalizations verbatim to `pressure-tests/baseline.md`. See [PRESSURE-TESTING.md](PRESSURE-TESTING.md).

4. **Design the architecture** — decide file structure. Over 300 lines total → split into SKILL.md + FORMAT.md + STATE.md + GOLDEN-RULES.md + INTEGRATION.md. See [DESIGN.md](DESIGN.md) and [FORMAT.md](FORMAT.md).

5. **Write the metadata** — `name` and `description` in YAML frontmatter. Description includes trigger keywords, not workflow summary. See [WRITING.md](WRITING.md).

6. **Write SKILL.md** — numbered workflow steps (one line each with a pointer), self-review checklist, golden rules, anti-rationalization counter-table, termination labels, iron-law verification gate language. No inline code blocks. See [FORMAT.md](FORMAT.md).

7. **Write companion files** — FORMAT.md (output templates), STATE.md (run state schema, resume protocol), GOLDEN-RULES.md (rules + counter-table), INTEGRATION.md (composition with deep-qa, deep-design, degraded-mode fallbacks). One file per concern, each under 500 lines. See [FORMAT.md](FORMAT.md).

8. **Close loopholes with REFACTOR pass** — spawn subagent WITH the skill on the same scenarios. Record verbatim outputs to `pressure-tests/with-skill.md`. For any new rationalization that slipped past: add a counter-table row, add a red-flag line, add a golden rule. Re-run. Repeat until `pressure-tests/with-skill.md` shows zero violations. See [PRESSURE-TESTING.md](PRESSURE-TESTING.md).

9. **Evaluate** — test the skill with positive, implicit, noisy, and negative prompts (separate from pressure tests). Verify progressive disclosure works. See [EVALUATION.md](EVALUATION.md).

10. **Deploy with pressure-test hand-off** — hand the user the skill + the 3-5 pressure scenarios and the `pressure-tests/` log. Direct them to run the scenarios themselves before relying on the skill. See [PRESSURE-TESTING.md](PRESSURE-TESTING.md).

### Session extraction track (Steps S1-S5)

Use this track when the current session uncovered a repeatable workflow that should become a reusable skill. Trigger: "turn this into a skill", "extract from session", "skillify this", "save this workflow".

S1. **Identify the repeatable task** — what did this session accomplish that will recur? Name it.

S2. **Extract the skeleton** — from conversation context, pull: inputs, ordered steps, success criteria, constraints/pitfalls.

S3. **Classify destination** — decide where the skill belongs:
  - **Full skill** (`~/.claude/skills/<name>/SKILL.md`) → proceed to workflow or reference track above for the full build.
  - **Learned skill** (lightweight, project-scoped) → continue S4-S5.
  - **Documentation only** → write to appropriate doc file, done.

S4. **Draft the learned skill file** — must start with YAML frontmatter:
  ```yaml
  ---
  name: <skill-name>
  description: <one-line description>
  triggers:
    - <trigger-1>
    - <trigger-2>
  ---
  ```
  Write to one of:
  - `~/.claude/skills/<skill-name>/SKILL.md` (user-level, reusable across projects)
  - `.claude/skills/<skill-name>/SKILL.md` (project-level, committed with repo)

S5. **Flag open questions** — if any branching decisions or fuzzy steps remain, note them explicitly in the skill file rather than leaving them implicit. Terminate with label `shipped_lite`.

### Reference skill track (Steps R1-R6)

R1. **Understand the tool** — what CLI/API/service does this skill document? What commands, endpoints, or patterns does a user need? See [DESIGN.md](DESIGN.md).

R2. **Design the structure** — SKILL.md as the primary guide with inline code examples. Use `references/` subdirectory for overflow content (quick-start, API reference, troubleshooting, examples). See [FORMAT.md](FORMAT.md).

R3. **Write the metadata** — `name` and `description` in YAML frontmatter. Description includes trigger keywords. See [WRITING.md](WRITING.md).

R4. **Write SKILL.md** — quick-reference tables, inline code examples, golden rules (hard constraints for the tool), common workflows. Code blocks are welcome. See [FORMAT.md](FORMAT.md).

R5. **Write reference files** — `references/` subdirectory with topic-named files. Each under 500 lines. See [FORMAT.md](FORMAT.md).

R6. **Verify accuracy** — run 3-5 representative commands from the skill and confirm they work. Save results to `verification/commands-tested.md`. See [PRESSURE-TESTING.md](PRESSURE-TESTING.md).

## Honest termination labels (for this skill's own output)

Every invocation of `create-skill` terminates with exactly one label in the final report:

| Label | Meaning |
|---|---|
| `shipped` | Workflow skill: RED baseline captured, GREEN re-run passes, REFACTOR loopholes closed, pressure scenarios handed to user. Reference skill: accuracy verification passed. |
| `shipped_degraded` | Skill files written, but pressure-test/verification phase was skipped or incomplete. Must be explicitly tagged with reason in the final report. |
| `shipped_lite` | Reference or utility skill under 100 lines. Accuracy verified but exempt from full pressure-testing. |
| `blocked_needs_input` | Domain unclear after Step 0/1; cannot proceed without user clarification. |
| `cancelled` | User interrupted. |

Never label a run `done`, `complete`, or `all good`. Every run produces one of the above labels.

## Self-review checklist

Before delivering, verify ALL applicable items:

**All skill types:**
- [ ] Skill type classified (workflow / reference / shim) at Step 0
- [ ] `description` is specific, third-person, includes trigger keywords, does NOT summarize workflow
- [ ] Every reference/companion file is linked from SKILL.md with a one-line summary
- [ ] Golden rules are hard and mechanical (never "consider" or "try to")
- [ ] Reference files are one level deep (SKILL.md → file, never file → file → file)
- [ ] Skill works when invoked explicitly (`/skill-name`) AND when Claude triggers it from a matching request
- [ ] No vague quality language ("clean", "good", "appropriate") — replaced with concrete specs
- [ ] Final report uses one of the five termination labels above

**Workflow skills only:**
- [ ] SKILL.md is under 100 lines of content (excluding frontmatter) for flat skills, or a lean map for companion-split skills
- [ ] SKILL.md has zero inline code blocks (all code is in companion files)
- [ ] Anti-rationalization counter-table present (min 5 rows for discipline skills, min 3 for one-shots)
- [ ] Honest termination labels defined (finite enum, 3-6 labels)
- [ ] Iron-law verification gate language present (concrete evidence file requirement, not "verify")
- [ ] At least one feedback loop encoded (test → verify → fix → re-test)
- [ ] `pressure-tests/scenarios.md`, `pressure-tests/baseline.md`, `pressure-tests/with-skill.md` all exist on disk
- [ ] `pressure-tests/with-skill.md` shows zero violations on all scenarios (or degraded tag with reason)
- [ ] Companion split applied if total skill content > 300 lines (SKILL.md + FORMAT.md + STATE.md + GOLDEN-RULES.md + INTEGRATION.md)

**Reference skills only:**
- [ ] Code examples are inline, copy-paste ready, and tested
- [ ] `references/` subdirectory used for overflow (not FORMAT.md/STATE.md pattern)
- [ ] `verification/commands-tested.md` exists with results from 3-5 representative commands
- [ ] Quick-reference tables present for common operations

## Golden rules for skill creation

Hard rules. Never violate these.

1. **Classify type first.** Every skill is workflow, reference, or shim. Classify at Step 0. The type determines which rules apply. Applying workflow discipline to a reference skill wastes effort; skipping it on a workflow skill invites drift.
2. **SKILL.md is a map (workflow) or a guide (reference).** Workflow SKILL.md: no code blocks, point to companion files. Reference SKILL.md: code blocks are the value — inline examples, quick-reference tables, CLI patterns.
3. **Description is discovery, not summary.** Claude picks skills from description alone. If the description summarizes the workflow, Claude follows the description instead of reading the skill body. Describe triggers, not process.
4. **RED before GREEN (workflow skills).** If there is no `pressure-tests/baseline.md` recording what a subagent does WITHOUT the skill, the workflow skill is unverified. Delete it. Start over. Reference skills use accuracy verification instead.
5. **Golden rules prevent drift.** Every skill must encode 3-8 hard mechanical rules specific to its domain. Use imperative voice: "Never", "Always", "Must".
6. **Anti-rationalization counter-table is mandatory for workflow skills.** Every workflow skill ships with an Excuse → Reality table capturing the exact verbatim excuses observed in RED baseline.
7. **Termination labels are a finite enum (workflow skills).** Workflow skills define 3-6 exhaustive labels. Never "done" / "no issues" / "all good" as a label. Reference skills don't need them.
8. **Iron-law gates beat gentle reminders (workflow skills).** A rule that says "verify tests pass" is weaker than a gate that refuses to claim completion unless `test-output.txt` exists on disk and matches a pattern.
9. **Feedback loops are the product.** A skill without a concrete verification cycle (do → check → diagnose → fix → re-check) is a suggestion, not a skill.
10. **Diagnose, don't retry.** When the agent gets stuck, the skill must tell it how to figure out WHY, not just "try again." Include a symptom → cause → fix table.
11. **Concrete beats abstract.** "Use a clean design" produces slop. "Define CSS variables on `:root`, use `system-ui`, add hover states" produces consistency. Replace every adjective with a specification.
12. **Progressive disclosure saves context.** Only SKILL.md loads on trigger. Companion files load when Claude reads them. Put expensive content in companion files.
13. **Reference skills use `references/`, workflow skills use companion split.** Don't mix the patterns — FORMAT.md/STATE.md for workflow; `references/quick-start.md` for reference.
14. **If it's not in the skill files, it doesn't exist.** The agent can only see what's in the skill directory. Every constraint must live in the skill files or it will be ignored.

## Anti-rationalization counter-table (for skill authoring)

This counter-table captures excuses observed when agents (and authors) try to skip the discipline of this skill. Every skill produced by `create-skill` must include its own counter-table with excuses specific to that skill's domain.

| Excuse | Reality |
|---|---|
| "Pressure-testing is overkill for this skill." | Workflow skills: no skill ships without a RED baseline. Reference skills: run accuracy verification instead. Shim skills: exempt. Classify the type first. |
| "I already wrote the skill; I'll test after." | Workflow: skill body written before baseline is unverified documentation. Delete it. Run Step 2 first. Reference: write the skill, then verify commands work. |
| "The agent obviously understands this rule." | Obvious to you ≠ obvious under pressure. Run the scenarios anyway. |
| "I'll just add a counter-table row I imagined the agent might say." | Counter-table rows come from observed baseline output, not imagination. Unobserved excuses miss the real rationalizations. |
| "This is a reference skill so I can skip all the rules." | Reference skills still need: trigger-based descriptions, golden rules, progressive disclosure, tested code examples. They skip: counter-tables, termination labels, pressure-tests, iron-law gates. |
| "Companion-split is bureaucracy for a short skill." | Under 300 lines: keep it flat. Over 300: split. The split is not optional above the threshold because long SKILL.md bodies get partial-read by Claude. |
| "Termination label `done` is fine, I mean `complete`." | Not fine. The enum must be honest — `complete` means every criterion verified on disk this session. `done` is ambiguous and invites self-approval. |
| "I'll put FORMAT.md and STATE.md in my reference skill." | Reference skills use `references/` subdirectory with topic-named files. FORMAT.md/STATE.md is the workflow companion pattern. Don't mix them. |

## Reference files

| File | Contents |
|------|----------|
| [DESIGN.md](DESIGN.md) | How to analyze a domain, design file structure, apply progressive disclosure |
| [WRITING.md](WRITING.md) | How to write metadata, SKILL.md body, reference files, golden rules, checklists |
| [FORMAT.md](FORMAT.md) | Output template for a produced skill (SKILL.md + companion files), mandatory sections including counter-table and termination labels |
| [GOLDEN-RULES.md](GOLDEN-RULES.md) | Consolidated rules for skill authoring with per-rule concrete examples and detection criteria |
| [PRESSURE-TESTING.md](PRESSURE-TESTING.md) | RED-GREEN-REFACTOR protocol for skills: how to write pressure scenarios, run the baseline, interpret violations, close loopholes |
| [INTEGRATION.md](INTEGRATION.md) | How `create-skill` composes with `deep-qa` for skill review, and degraded-mode fallbacks |
| [EVALUATION.md](EVALUATION.md) | How to test skills with positive, implicit, noisy, and negative prompts |

# Writing Skill Content

How to write effective metadata, SKILL.md, reference files, golden rules, and checklists.

This document covers the mechanical "how do I write good content" layer. Companions:

- [FORMAT.md](FORMAT.md) defines the MANDATORY sections every produced skill must contain — counter-table, termination labels, iron-law gate language.
- [GOLDEN-RULES.md](GOLDEN-RULES.md) is the consolidated rule set that every produced skill must absorb.
- [PRESSURE-TESTING.md](PRESSURE-TESTING.md) is the RED-GREEN-REFACTOR protocol — authored pressure scenarios, RED baseline, GREEN verification, REFACTOR loophole closing.
- [INTEGRATION.md](INTEGRATION.md) documents composition with `deep-qa` for skill review and `deep-design` for design review, including degraded-mode fallbacks.

**Iron law:** No skill ships without a `pressure-tests/baseline.md` file on disk recording what a subagent does WITHOUT the skill loaded. Write SKILL.md before baseline exists → delete SKILL.md → go to [PRESSURE-TESTING.md](PRESSURE-TESTING.md) Step 2.

## Metadata: name and description

### Name

- Lowercase letters, numbers, hyphens only (no parentheses, special chars)
- Max 64 characters
- **Use active voice, verb-first.** Name by what you DO or the core insight, not the category.
  - ✅ `creating-skills`, `condition-based-waiting`, `flatten-with-flags`, `root-cause-tracing`
  - ❌ `skill-creation`, `async-test-helpers`, `data-structure-refactoring`, `debugging-techniques`
- **Gerunds (-ing) work well for processes** (the ongoing action you're taking): `creating-skills`, `testing-skills`, `debugging-with-logs`.
- **Verb-noun works for one-shot generators**: `create-skill`, `develop-board-game`, `review-pr`.
- Avoid generic names: `helper`, `utils`, `tool`, `reference`, `details`.

### Description

The description is a search index entry. Claude uses it to decide whether to load the skill. Write it in third person.

**Formula**: `Use when [trigger conditions, symptoms, and phrases].`

⚠️ **The description is ONLY triggers, NEVER a workflow summary.** When a description summarizes what the skill does, Claude follows the description as a shortcut and skips the skill body. Empirical example: a description that said "runs two-stage review" caused Claude to do ONE review, because the skill body explaining the two stages was never read. Describe the *when*, not the *how*.

```yaml
# ✅ GOOD: just triggers, no workflow summary
description: Use when creating, editing, scaffolding, or reviewing a Claude Code skill, slash command, or agent capability.

# ✅ GOOD: triggers including symptoms and error messages
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ❌ BAD: summarizes the workflow — Claude will follow this shortcut instead of reading the skill
description: Use when creating skills — runs RED-GREEN-REFACTOR, writes companion files, closes loopholes.

# ❌ BAD: states what the skill DOES rather than WHEN to use it
description: Creates well-structured skills by applying harness engineering best practices.

# ❌ BAD: vague, no triggers
description: Helps with creating things.

# ❌ BAD: first person
description: I can help you build skills.
```

**Keyword coverage**: Claude does substring matching on descriptions. If "edit" is missing, a user saying "edit my skill" won't route here. Include every word a user might type.

Cover these keyword classes:
- **Synonyms**: create/build/scaffold/generate/write; edit/modify/update/revise; review/audit/check/verify
- **Error messages the user might paste**: "Hook timed out", "ENOTEMPTY", "race condition"
- **Symptoms**: "flaky", "hanging", "intermittent", "pollution"
- **Tools and file types**: actual CLI names, library names, extensions (`.ipynb`, `.pptx`)
- **Alternative terminology**: "slash command" vs "skill", "subagent" vs "agent capability"

**Length**: Under 1024 characters total (frontmatter limit). Aim for 1-3 sentences of pure triggers — a workflow summary inflates length without helping routing.

### Description pattern catalog (from real skills)

These before/after pairs are drawn from an audit of 136 existing skills. Use them as models.

**Good trigger-based descriptions:**
- `ci-health-report`: "Use when assessing CI pipeline health, build failure trends, or flaky test patterns for a Jenkins job."
- `deploy-status-report`: "Use when checking deployment status, rollout progress, or release health across Spinnaker pipelines."
- `flaky-test-diagnoser`: "Use when a test fails intermittently and you need to determine if it's genuinely flaky or consistently broken."
- `slack-digest`: "Use when summarizing Slack channel activity, catching up on threads, or generating channel digests."

**Bad workflow-summary descriptions (avoid):**
- `build`: "Create any artifact: code, experiments, reports, presentations, pipelines. Auto-plans if needed..." → Describes what it does, not when to use it. Better: "Use when building, scaffolding, or implementing code, experiments, reports, or pipelines from a spec or idea."
- `fix`: "Something is broken. Hypothesis-driven root cause analysis, fix, verify, loop until resolved." → Summarizes the process. Better: "Use when something is broken — a bug, test failure, build error, or unexpected behavior that needs diagnosis and fix."
- `review`: "Adversarial multi-perspective critique of any artifact. Parallel critics with different focus dimensions..." → Describes the mechanism. Better: "Use when reviewing, critiquing, or auditing any artifact — code, spec, design doc, PR, or research report."
- `monitor`: "Health checking for services, pipelines, code, teams, or deployments. Parameterized by data source." → Summarizes architecture. Better: "Use when monitoring health of services, pipelines, code quality, team metrics, or deployments."

## Token efficiency (critical for hot skills)

Every skill's `name` and `description` load into the system prompt for every conversation. A bloated description burns context across every turn, not just when the skill triggers.

**Word-count targets:**

| Skill type | Target |
|---|---|
| Getting-started / always-loaded workflows | <150 words total |
| Frequently-loaded (5+ hits per session) | <200 words total |
| Standard workflow skills | <500 words in SKILL.md body |
| Long-tail skills (loaded rarely) | <1000 words in SKILL.md body; unlimited in companion files |

**Token-efficiency techniques:**

- **Move detail to tool help**: `Run --help for flags` beats listing every flag.
- **Cross-reference instead of repeat**: `Use [other-skill] for workflow` beats re-stating it.
- **Compress examples**: one minimal example > three verbose ones.
- **Eliminate redundancy**: don't repeat what's in cross-referenced skills, don't explain what's obvious from command syntax.
- **Push heavy content to companion files**: companion files load only when Claude reads them. Use this.

**Verification:**

```bash
wc -w SKILL.md   # body word count
```

If SKILL.md exceeds the target, either delete content or move it to a companion file. Never pad for "thoroughness".

## SKILL.md body: the table of contents

Every produced SKILL.md has the mandatory sections defined in [FORMAT.md](FORMAT.md):

1. YAML frontmatter
2. Title + one-line purpose
3. Execution Model (workflow skills only)
4. Workflow (numbered, one line each)
5. Honest termination labels (workflow skills only)
6. Self-review checklist
7. Golden rules
8. Anti-rationalization counter-table
9. Reference/companion file index

This document covers the mechanics of writing each section well. [FORMAT.md](FORMAT.md) is the authoritative template.

### 1. Title and one-line purpose

```markdown
# Skill Name

One sentence: what this skill builds and how.
```

### 2. Workflow

Numbered steps, one line each. Each step names what to do and points to a reference file for details:

```markdown
## Workflow

1. **Verb phrase** — brief description. See [REFERENCE.md](REFERENCE.md).
2. **Verb phrase** — brief description. See [OTHER.md](OTHER.md).
...
```

Rules for workflow steps:
- Start each step with a **bold verb phrase**
- Follow with an em-dash and a one-line description
- End with a link to the relevant reference file
- No code blocks, no multi-line explanations
- 5-12 steps is the sweet spot. Fewer means the skill is trivial. More means it needs splitting.

### 3. Self-review checklist

Checkbox items that the agent must verify after completing the workflow:

```markdown
## Self-review checklist

Before delivering, verify ALL:

- [ ] Concrete, verifiable condition
- [ ] Another concrete condition
...
```

Rules for checklist items:
- Every item must be objectively verifiable (can you answer yes/no without judgment?)
- Bad: "Code is clean" (subjective)
- Good: "No console errors during a full run" (objective)
- Bad: "Tests pass" (too vague)
- Good: "All 5 test categories pass: init, moves, win, negative, visual" (specific)
- 6-12 items. Fewer means you're not checking enough. More means you're micromanaging.

### 4. Golden rules

Hard mechanical rules specific to this skill's domain:

```markdown
## Golden rules

Hard rules. Never violate these.

1. **Rule name.** Imperative explanation of what to always/never do.
2. **Rule name.** Another hard rule.
...
```

Rules for golden rules:
- 3-8 rules per skill
- Use imperative voice: "Never", "Always", "Must", "Do not"
- Never use soft language: "Consider", "Try to", "Prefer", "Should"
- Each rule prevents a specific failure mode **observed in the RED baseline** (not hypothetical)
- Each rule is mechanical — an agent can follow it without judgment

**How to derive golden rules**: Look at the rationalizations captured in `pressure-tests/baseline.md`. For each observed rationalization, write a rule that prevents it:

| Observed rationalization | Golden rule |
|---|---|
| "Tests probably pass, I'll skip running them" | "Never claim completion without `test-output.txt` on disk matching `Tests: \d+ passed, 0 failed` from this session." |
| "SKILL.md is cleaner if I add examples inline" | "SKILL.md is a map. If you're writing a code block in SKILL.md, it belongs in a companion file." |
| "Obvious what to do, I'll skip the description keywords" | "Description is discovery. If the description doesn't contain keywords a user would say, the skill won't trigger." |
| "I'll hand-wave the verification" | "Every completion claim is file-gated. `Verify` / `check` / `ensure` without a concrete file-existence check is forbidden." |

### 5. Anti-rationalization counter-table

MANDATORY section (new). Captures the exact rationalizations observed in `pressure-tests/baseline.md` and pairs each with a concrete reality.

```markdown
## Anti-rationalization counter-table

| Excuse | Reality |
|---|---|
| "<verbatim excuse observed in baseline>" | <specific action the agent must take instead> |
```

Rules:
- Minimum 5 rows for discipline-enforcing skills. Minimum 3 rows for one-shot generators.
- Every row references a real excuse observed in `pressure-tests/baseline.md`. No imagined rows.
- Reality column is a concrete action, not a platitude.

Bad row: `| "Tests will pass eventually" | Be patient. |` — platitude, not an action.
Good row: `| "Tests will pass eventually" | Run `npm test`, save output to `test-output.txt`, only claim completion if exit code is 0. |` — concrete action.

### 6. Honest termination labels (workflow skills only)

MANDATORY for any produced skill that makes completion claims. A finite enum, 3-6 labels, each with an observable condition on disk.

```markdown
## Honest termination labels

| Label | Meaning |
|---|---|
| `complete` | Every AC verified green; zero unresolved critical/major defects. |
| `partial_with_accepted_unfixed` | Critical defects fixed; some major/minor explicitly accepted with rationale. |
| `blocked_unresolved` | Critical defect with no path forward AND budget not exhausted. |
| `budget_exhausted` | Fix budget reached with unresolved critical/major defects. |
| `cancelled` | User interrupted. |
```

Never `done` / `all good` / `no issues remain`. One of the N labels must be `cancelled`. Every label's meaning references observable evidence files, not the coordinator's judgment.

### 7. Reference file index

A table linking to every reference file:

```markdown
## Reference files

| File | Contents |
|------|----------|
| [FILE.md](FILE.md) | One-line summary |
```

## Reference files: the details

Each reference file covers one concern (architecture, testing, visual design, workflow details, etc.).

### Structure of a reference file

```markdown
# Topic Name

Brief (1-2 sentence) purpose statement.

## Section 1
[Content]

## Section 2
[Content]
```

### What goes in reference files

- **Code patterns and templates**: Full code blocks, boilerplate, example implementations
- **Detailed step instructions**: Multi-paragraph explanations of how to do something
- **Domain-specific reference**: APIs, schemas, protocol definitions, data formats
- **Examples**: Input/output pairs, before/after comparisons
- **Testing methodology**: Test patterns, verification steps, checklists
- **Visual standards**: CSS systems, design tokens, layout patterns
- **Failure diagnosis**: Symptom → cause → fix tables

### Writing effective reference files

**Start with context, not instructions.** The first paragraph should tell Claude what this file is about and when to use it. Claude may read just the first few lines to decide whether to continue.

**Use headers liberally.** Claude can scan headers to find the right section. A reference file with no headers forces a full read.

**Code blocks should be copy-paste ready.** Don't write pseudocode unless the intent is for Claude to adapt it significantly. If the code should be used as-is, make it complete and runnable.

**Tables for structured data.** Decision trees, symptom→fix mappings, and option comparisons are better as tables than prose.

**Keep under 500 lines.** If approaching this limit, split into two files. Each file should have a focused topic.

## Writing feedback loops

Every skill needs at least one feedback loop — a cycle where the agent does work, verifies it, and fixes issues. The most impactful skill improvement you can make is adding a concrete feedback loop.

### Anatomy of a feedback loop

```
Do → Check → Diagnose → Fix → Re-check
```

Each step must be concrete:

| Step | Vague (bad) | Concrete (good) |
|---|---|---|
| Do | "Write the code" | "Implement `getValidMoves` as a pure function" |
| Check | "Test it" | "Run `npx playwright test` and verify zero failures" |
| Diagnose | "Fix any issues" | "If assertion fails on game state, log `applyMove` input/output" |
| Fix | "Update the code" | "Fix the specific function identified in diagnosis" |
| Re-check | "Test again" | "Re-run the same test suite, verify the previously failing test now passes" |

### Types of feedback loops

**Automated test loop** (strongest): Run a test suite, parse results, fix failures.
```
Write code → Run tests → If failures: read error, fix specific issue → Re-run tests
```

**Self-review loop**: Agent reviews its own output against a checklist.
```
Complete task → Check each item in self-review checklist → Fix any failures → Re-check
```

**Visual verification loop**: Agent takes a screenshot and inspects it.
```
Render UI → Take screenshot → Check against visual standards → Fix issues → Re-render
```

**Rules audit loop**: Agent verifies domain rules are satisfied.
```
Implement feature → Walk through each rule → Verify with test case → Fix gaps
```

## Writing failure diagnosis

When the agent gets stuck, the skill must help it figure out WHY. The pattern is a table:

```markdown
| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| Specific observable problem | Root cause | Specific action to take |
```

Rules:
- Symptoms must be things the agent can observe (error messages, unexpected output, test failures)
- Causes must be specific (not "something went wrong")
- Fixes must be actions (not "investigate further")
- Include the most common 5-10 failure modes
- End with a catch-all: "If none of the above: log the state before and after the failing operation and inspect the diff."

## Avoiding AI slop

"AI slop" is output that looks reasonable but is generic and inconsistent. It happens when instructions are vague.

### The adjective test

Search your skill for adjectives. For each one, ask: "Could two runs of this skill produce different output because this adjective is subjective?"

| Slop | Concrete replacement |
|---|---|
| "Clean code" | "Functions under 30 lines, no nested callbacks deeper than 2" |
| "Good design" | "CSS variables on `:root`, `system-ui` font, hover states on interactives" |
| "Appropriate error handling" | "Every `catch` logs the error and returns a structured `{ success: false, error: string }`" |
| "Well-tested" | "Unit tests for all pure functions, integration test for the main workflow, negative tests for invalid input" |
| "Clear documentation" | "JSDoc on exported functions, README with install/run/test sections" |

### The copy-paste test

For any code pattern in your skill: could an agent copy it verbatim and get a working result? If not, make it more complete. Pseudocode invites improvisation. Complete code enforces consistency.

### The diff test

Run the skill twice on the same input. Diff the outputs. Anything that differs between runs indicates an underspecified instruction. Fix the instruction to make it deterministic.

## Anti-patterns to avoid

These are concrete authoring mistakes that produce broken skills. Each has a fix.

### ❌ Narrative example
"In session 2025-10-03, we found empty projectDir caused..."
**Why bad:** too specific, non-reusable, degrades over time as the referenced events fade.
**Fix:** restate as a general pattern: "When projectDir is empty, ..."

### ❌ Multi-language dilution
`example-js.js`, `example-py.py`, `example-go.go`
**Why bad:** each implementation is mediocre, maintenance is 3x, no single example is authoritative.
**Fix:** one excellent example in the most relevant language. Claude ports accurately to other languages.

### ❌ Code blocks in workflow SKILL.md
A workflow skill whose SKILL.md contains inline code forces every triggered invocation to pay the token cost of that code, even for agents that won't execute it.
**Fix:** move code to a companion file. SKILL.md points to the file; the file is read only when needed.
**Exception:** Reference skills. Code blocks are the primary value in reference skills — inline examples show users/agents how to use the tool. For reference skills, keep code blocks in SKILL.md.

### ❌ Code in flowcharts
```dot
step1 [label="import fs"];
step2 [label="read file"];
```
**Why bad:** not copy-pasteable, harder to read than a code block, node labels carry no semantics.
**Fix:** use a numbered list or a code block. Flowcharts are for branching decision points, not linear sequences.

### ❌ Generic labels
`helper1`, `helper2`, `step3`, `pattern4`, `option-a`, `option-b`
**Why bad:** labels must carry semantic meaning so the agent knows what it's selecting.
**Fix:** name each item by what it does: `retry-with-backoff`, `fail-fast`, `lazy-load`.

### ❌ Workflow summary in description
`description: Use when creating skills — runs RED-GREEN-REFACTOR across N phases`
**Why bad:** Claude follows the description as a shortcut and skips the skill body. A skill body describing 5 phases becomes a 1-phase skill in practice.
**Fix:** triggers only. `description: Use when creating, editing, or reviewing a skill.`

### ❌ Soft rules ("consider", "try to", "prefer")
A rule that says "Consider running tests" is a suggestion agents skip under pressure.
**Fix:** hard imperative. "Run tests. If `test-output.txt` does not exist, do not claim completion."

### ❌ Iron-law gate weakened to a reminder
`Verify tests pass before completion` is a reminder, not a gate.
**Fix:** file-gated check. `Before claiming completion, read test-output.txt and assert it matches 'Tests: \d+ passed, 0 failed' from this session.`

### ❌ Inline table-of-contents in SKILL.md for a flat skill
A skill under 300 lines that still ships with FORMAT.md + STATE.md + etc. is over-engineered — companion-split is for skills that need it.
**Fix:** keep flat skills flat. Split only when you cross the 300-line threshold.

## Technology selection

Skills that produce code must guide technology choices. Agents work best with boring technology.

### Prefer boring technology

"Boring" means: composable, stable API, well-documented, widely used, well-represented in training data. Agents model boring technology accurately because they've seen thousands of examples.

| Boring (prefer) | Exotic (avoid unless necessary) |
|---|---|
| Vanilla JS, HTML, CSS | Svelte, Solid, HTMX |
| `fetch` API | Axios, superagent |
| CSS Grid / Flexbox | Tailwind (requires build), CSS-in-JS |
| Node.js built-ins | Obscure npm packages |
| SQLite | Exotic databases |
| `system-ui` font stack | Custom font loading pipelines |

### Reimplement over wrapping opaque dependencies

When a library is opaque, brittle, or poorly documented, it's cheaper for the agent to reimplement the needed subset than to fight upstream behavior. A skill should say: "Implement X directly using Y" rather than "Install library Z."

Example: Instead of depending on a game physics library, implement the specific collision detection the game needs with 20 lines of math.

### Centralize invariants in shared functions

Agents replicate patterns they see — even bad ones. If the same logic appears in 3 places, the agent will copy-paste and eventually drift. Instead:

- Extract common logic into named functions
- Define constants in one place and import them
- Use a config object for values that might change

This is the "shared utility packages over hand-rolled helpers" principle. One function, one truth.

## Promoting rules from docs to code

Documentation says what to do. Code enforces it. When a doc instruction is repeatedly violated, promote it.

### The promotion ladder

```
1. Comment         → weakest: agents often skip comments
2. SKILL.md rule   → medium: agents follow golden rules most of the time
3. Validation fn   → strong: code rejects invalid output at runtime
4. Linter/test     → strongest: CI catches violations before they land
```

When possible, encode rules as validation functions or tests, not just instructions. A rule that says "all moves must be validated" is weaker than a `performMove` function that actually calls `getValidMoves` and rejects invalid input.

### Error messages as agent context

When writing validation functions, make error messages self-documenting:

```javascript
// Bad: agent doesn't know how to fix this
throw new Error('Invalid move');

// Good: agent knows exactly what went wrong and what to do
throw new Error(
  `Invalid move: {row: ${move.row}, col: ${move.col}} is not in validMoves. ` +
  `Current player: ${state.currentPlayer}. ` +
  `Valid moves: ${JSON.stringify(state.validMoves.slice(0, 5))}...`
);
```

Custom linters and validators with remediation instructions become force multipliers: once encoded, they correct the agent everywhere at once, automatically.

## Discoverability: if it's not in the files, it doesn't exist

The agent can only see what's in the skill directory and the user's repo. External knowledge is invisible.

### What must live in skill files

- All domain conventions and patterns
- All technology choices and their rationale
- All structural requirements (file naming, data shapes, API contracts)
- All known failure modes and their fixes
- All quality standards with concrete specifications

### What's invisible to the agent

- Slack conversations about "how we usually do this"
- External documentation not linked or inlined
- Team norms that aren't written down
- Assumptions that "everyone knows"

If a constraint matters, write it in a skill file. If it's not written, it will be violated.

## Architectural philosophy

### Enforce boundaries centrally, allow autonomy locally

A skill should be strict about boundaries (state shape, API contracts, validation rules, file structure) but permissive about implementation details within those boundaries.

**Enforce centrally**: Data shapes, naming conventions, required functions, test API signatures, CSS variable system, file layout.

**Allow autonomy locally**: How to implement a specific game rule, which CSS colors to choose within the variable system, how to structure internal helper functions, AI difficulty algorithm.

This gives the agent guardrails without micromanaging.

### Corrections are cheap, waiting is expensive

In an agent workflow, it's faster to build something, test it, find problems, and fix them than to plan everything perfectly upfront. Skills should encode a "build → test → fix" loop, not a "plan exhaustively → build perfectly" approach.

This doesn't mean skip planning. It means: get to testable output fast, then iterate based on real failures rather than hypothetical ones.