Superpowers Writing Skills

Writing Skills (for Reasonix)

Overview

Writing skills IS TDD for process docs. Write test cases (pressure scenarios, subagents). Watch fail (baseline). Write skill. Watch pass (agent complies). Refactor (close loopholes).

Core principle: Didn't watch an agent fail without the skill? Don't know it teaches the right thing.

REQUIRED BACKGROUND: Know superpowers-test-driven-development first — defines RED-GREEN-REFACTOR. This adapts it to docs.

Platform spec: Full Reasonix skill/hook/MCP contract → extending-reasonix. This = authoring discipline; that = exhaustive spec.

What is a Skill?

Reusable playbook the model invokes via run_skill (user: /name); read_only_skill loads it in read-only sessions. Two kinds:

• Inline — body folds into the turn as a tool result. Default.
• Subagent (runAs: subagent) — body = a child's system prompt; runs isolated, returns only its final answer. Use only when work is context-heavy and only the conclusion matters.

ARE: reusable techniques, patterns, tools, reference guides. NOT: narratives of solving something once.

Reasonix Skill Anatomy (get these right)

Where skills live & how found

• Discovery roots, highest priority first: project {.reasonix,.agents,.agent,.claude}/skills/ → [skills] paths in reasonix.toml → home ~/{.reasonix,...}/skills/ → built-ins.
• First match by name wins (user review overrides built-in). Layout: <root>/skills/<name>/SKILL.md; flat <name>.md works too.

Name

Regex: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$ — letters/digits/./_/-, ≤64 chars, alphanumeric start. Frontmatter name: overrides the dir stem.

Frontmatter — YAML, with Reasonix compatibility flattening

• --- opens, next --- closes. Unclosed fence → WHOLE file is the body (no frontmatter). Always close it.
• YAML is parsed with yaml.v3. Keys are lowercased (runAs=runas), scalar values become strings, sequences are comma-joined, and nested mappings are flattened to their child keys for legacy consumers. Block scalars (>/|) work. Invalid YAML yields an empty frontmatter map, so validate the file after editing.

Recognized keys:

Dynamic session-context catalog = 130 chars per line

The host supplies the current skill catalog in session context, with entries clipped to 130 chars incl. name and a shared 4000-char description budget. So:

• Front-load triggers — tail gets cut. Keep it short: 22-char name → ~100 chars before truncation.
• For manual-only worker skills, set invocation: manual; still supply a useful description.

references/ auto-fold (undocumented, load-bearing)

Every references/*.md sibling is appended to the body at load time, sorted by filename, each under ## Reference: <name>. Put depth material there — ships inline, no read_file. scripts/, assets/, references/, dot-dirs never scanned as nested skills. Subagent skill: references join the child's prompt — budget accordingly. Invoke bundled scripts through their interpreter in prose (bash scripts/tool.sh, node scripts/tool.js), never by bare path: packaging can strip executable bits.

Tool names are snake_case

Use literal names from the current Reasonix tool registry. Common names include read_file, write_file, edit_file, multi_edit, ls, glob, grep, bash, web_fetch, web_search, todo_write, run_skill, read_only_skill, use_capability, task, and explore. The current upstream boot code still mentions read_skill, but its constructor is absent from the skill package at the verified commit; do not author a new dependency on it until upstream resolves that mismatch. TitleCase Read/Edit/Bash don't exist; a typo in allowed-tools is silently dropped (subagent just lacks that tool).

Subagent Skills (authoring rules)

Body = child's system prompt, not a message to the parent. Write it as persona + procedure + output format; state the arguments/task string is its entire context.

• Only input = arguments string. No history. Tell it exactly what its task input contains.
• Check the active subagent tool policy before relying on nested delegation. Read-only skill runs can allow bounded read-only nested delegation. Fold required discipline (e.g. TDD) into the body or a references/ file when the child cannot load it.
• No mid-run back-and-forth; returns one final message. Design "ask the controller" as a reported status (e.g. NEEDS_CONTEXT), not a question.
• Scope allowed-tools to minimum. Empty = inherit all parent tools (minus meta-tools).

When to Create a Skill

Create when: technique wasn't obvious; you'd reuse it across projects; applies broadly; others benefit.

Don't create for: one-offs; standard documented practices; project conventions (→ AGENTS.md/REASONIX.md); mechanical constraints a hook/lint enforces (automate those — save skills for judgment calls).

Claude/Agent Search Optimization (CSO)

Critical: future agents must FIND your skill via the description.

Description = WHEN to use, not the step-by-step workflow

State the triggering condition. Name the single core action if you want — never enumerate the multi-step procedure. Its only job: get the skill discovered and loaded.

Why: spell out steps and the model follows the description, skips the body. "review between tasks" produced ONE review when the skill specified two; trimmed to the trigger, the model read the body and did both.

House style — validated, not dogma: on the floor model (deepseek-flash) a flat "Use when X" discovers less reliably than a forceful imperative naming the situation as a question + the one key move. So every description reads <trigger>? <STOP / Load first>[ — <one core action>]; the benchmark (bench/) proves it fires the right skill (12/12). Match that voice everywhere; no bare "Use when" lines.

yamlCopy code
# ❌ BAD: enumerates the workflow — the model follows this instead of the body
description: Dispatch a subagent per task, review between tasks, then merge
# ❌ BAD: flat trigger — weaker discovery on the floor model
description: Use when implementing a feature or bugfix
# ✅ GOOD: forceful trigger + the single core action (this repo's voice)
description: Writing or fixing any code? Load first — write the failing test before the code.

Keyword coverage & naming

• Use words the model would search for: error messages ("race condition", "ENOTEMPTY"), symptoms ("flaky", "hanging"), tools (command/library names).
• Voice: direct imperative/question ("Writing code? Load first…"), not third-person prose — it's injected into the system prompt as an instruction to act on.
• Name by what you DO or the core insight, verb-first / gerund: condition-based-waiting > async-test-helpers; superpowers-writing-plans > plan-authoring.

Cross-referencing other skills

Reference by bare name + explicit marker: **REQUIRED SUB-SKILL:** use the superpowers-test-driven-development skill. Don't read_file another SKILL.md, don't @-link it — use run_skill so scope resolution and auto-fold work.

The Iron Law (Same as TDD)

Copy code
NO SKILL WITHOUT A FAILING TEST FIRST

Applies to NEW skills AND EDITS. Wrote the skill before testing? Delete it. Start over. No exceptions for "simple additions" or "just a docs update."

RED-GREEN-REFACTOR for Skills (with Reasonix subagents)

RED — baseline. Dispatch a subagent (task, explore, or a throwaway subagent skill) with a pressure scenario, without your skill in context. Record verbatim: choices, rationalizations, which pressures triggered violations. Must see it fail first.

GREEN — minimal skill. Write a skill addressing those specific rationalizations. No content for hypothetical cases. Re-run the same scenarios with the skill loaded; agent should now comply.

REFACTOR — close loopholes. New rationalization? Add an explicit counter. Re-test until bulletproof.

See the Testing Skills With Subagents reference (auto-included below) for pressure types and methodology.

Bulletproofing Against Rationalization (for discipline skills)

• Close every loophole explicitly. Not "delete it" but "delete it. Start over. Don't keep it as reference. Don't adapt it. Delete means delete."
• Address spirit-vs-letter early: "Violating the letter of the rules is violating the spirit." Kills a whole class of rationalizations.
• Build a rationalization table from baseline testing — every excuse the agent made, with the reality.
• Create a Red Flags list for self-check before violating.

Flowchart Usage

Small inline dot flowchart ONLY for non-obvious decision points, loops where you might stop too early, or "A vs B" choices. Never for reference (tables), code (code blocks), or linear steps (numbered lists).

Anti-Patterns

• ❌ Narrative example ("In session 2025-10-03 we found…") — too specific, not reusable
• ❌ Multi-language dilution — one excellent example beats five mediocre
• ❌ Code inside flowcharts — can't copy-paste
• ❌ Generic labels (step1, helper2) — labels must carry meaning
• ❌ Enumerating the multi-step workflow in description — #1 discovery bug (single core action fine; the step sequence is not)
• ❌ Bloated bodies for a weak target model — on the floor model every extra paragraph competes with the rules; cut narrative and examples, fold discipline into terse tables, let the benchmark (not obra fidelity) decide what stays

STOP: Before Moving to the Next Skill

After writing ANY skill, STOP and finish its test+deploy cycle. Don't batch-create untested skills. Untested skill = untested code.

Skill Creation Checklist (TDD Adapted)

todo_write each item.

RED: [ ] pressure scenarios (3+ combined for discipline skills) · [ ] run WITHOUT skill, record baseline verbatim · [ ] identify rationalization patterns

GREEN: [ ] valid name (regex) · [ ] fence closed; name + description present · [ ] description trigger-first (single core action OK, never the full workflow), fits ~130-char line · [ ] imperative house voice · [ ] search keywords · [ ] addresses baseline failures · [ ] one excellent example · [ ] correct snake_case tools · [ ] run WITH skill, verify compliance

REFACTOR: [ ] counters for new rationalizations · [ ] rationalization table · [ ] red-flags list · [ ] re-test until bulletproof

Subagent skills: [ ] body = system prompt · [ ] states task is its entire context · [ ] allowed-tools minimal, valid names · [ ] check current delegation policy · [ ] no mid-run questions

Deploy: [ ] confirm discovery (appears in skill list / index) · [ ] invoke /name or run_skill to confirm it loads · [ ] commit to git

The Bottom Line

Creating skills IS TDD for process docs. Same Iron Law (no skill without a failing test first), same cycle (RED → GREEN → REFACTOR), same payoff (better quality, bulletproof results).