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 / read_skill (user: /name). 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 — Reasonix's OWN minimal parser, not real YAML

• --- opens, next --- closes. Unclosed fence → WHOLE file is the body (no frontmatter). Always close it.
• Lines = key: value. Keys lowercased (runAs=runas). Values trimmed of one quote layer. Empty value + - item lines = list (comma-joined), so allowed-tools can be a YAML list.
• No block scalars (>/|), no multi-line values, no nesting. One line per value.

Recognized keys:

Pinned index = 130 chars per line

System prompt lists every described skill as - <name> [🧬 subagent] — <description>, clipped to 130 chars incl. name, whole block capped at 4000 chars. So:

• Front-load triggers — tail gets cut. Keep it short: 22-char name → ~100 chars before truncation.
• Worker skill dispatched only by another skill can OMIT description to stay out of the index.

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.

Tool names are snake_case

Registry names only: read_file, write_file, edit_file, multi_edit, ls, glob, grep, bash, web_fetch, todo_write, run_skill, read_skill, task, explore. No web_search — only web_fetch. 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.
• Cannot recurse — run_skill/task/skill tools stripped. Can't load other skills. Fold needed discipline (e.g. TDD) into the body or a references/ file.
• 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.

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