Writing skills

Writes and edits skills the TDD way: a subagent first does the task without the skill and its mistakes are written down, then the smallest text that answers them goes in and the loopholes get closed. Use for a skill that other agents will load.

DocumentationPack: Superpowerslinkwriting-skills
Author
Source
obra/superpowers/skills/writing-skills @ 22f0b46
License
MIT

About this skill

What it does

Writing skills treats a skill as code and an agent run as its test. Before writing, you give a subagent a realistic task without the skill and record its mistakes and the exact excuses it gives. Then you write the smallest skill that answers those failures, rerun the scenario with it and close loopholes until the agent complies under pressure. Edits count too: an untested change is a violation. The skill also covers the description (only when to use the skill, never a summary of its steps, or agents follow the summary and skip the body), picking the form of guidance for each kind of failure, and micro-testing wording against a no-guidance control.

references/ holds the SKILL.md template with naming and size budgets (discovery.md), the testing method with pressure types (testing-skills-with-subagents.md), a worked campaign on CLAUDE.md variants (CLAUDE_MD_TESTING.md), rationalization tables and red flags (bulletproofing.md), persuasion principles and their ethical limits (persuasion-principles.md), flowchart rules (flowcharts.md, graphviz-conventions.dot) and Anthropic's authoring guide (anthropic-best-practices.md). render-graphs.js renders a SKILL.md's dot diagrams to SVG (node ./render-graphs.js ../some-skill, run from the skill folder); it needs Node and Graphviz.

When to use it, and when not

Use it when you create or change a skill that other agents will load, above all one that enforces a discipline agents are tempted to skip.

Skip it for one-off solutions, project conventions (those go in your instructions file) and rules a linter can enforce. Budget for it: baselines and micro-tests take many subagent runs.

How to run it

We do not copy this skill: its folder carries a copy of Anthropic's documentation (anthropic-best-practices.md), which the author's MIT licence does not cover. Install it from the author's repository, linked below: put the whole skills/writing-skills folder into your agent's skills folder. The agent picks the skill up by its description; to call it yourself:

  • Claude Code: /writing-skills, or ask for the skill by name.
  • Codex: $writing-skills.
  • Cursor: type / in the Agent chat and pick writing-skills.

Example: /writing-skills I want a skill that stops the agent from editing generated files. Run a baseline without it first and show me what goes wrong.

The skill requires test-driven-development as background; install it too. Two links in SKILL.md point to using-superpowers, which is not in our catalog; the text itself already names ~/.claude/skills/ and the cross-runtime ~/.agents/skills/.

How it differs from similar skills

Skill creator with evals from Anthropic also runs subagents with and without the skill, but writes the draft first, then grades the runs against assertions, adds a benchmark and a results viewer, and tunes the description on trigger queries. Skill writer by the Agent Skills spec from Sentry puts the weight on sources and structure: provenance, a SPEC.md, a short SKILL.md that routes to references/. Writing for agents covers wording and has no test procedure. Writing skills starts from a failing run and checks the text against what agents actually do — test-driven-development applied to prose. The bundled Anthropic guide says an agent can draft a skill unaided; this one adds the test loop.

Install

This skill is not copied to the catalog. Install it from the author's repository.

Open the source

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Superpowers

Brainstorming before you build

Finds out what you want to build and why: one question at a time, its understanding played back part by part, two or three approaches to pick from and a design doc, with no code until you approve it. Use for a new feature or change when the request leaves the essentials open.

Dispatching parallel agents

Splits independent problems between parallel subagents, each with one domain and a self-contained brief with scope, constraints and the report expected back, then checks their edits for conflicts and runs the full suite. Use when several unrelated things fail at once.

Executing plans

Runs a plan from writing-plans in the current session with no subagent per task: tasks in order through TDD, a ledger of progress and rulings that survives context compaction, and one fresh review of the whole branch at the end. Use when per-task review is not needed or there are no subagents.

Finishing a development branch

Finishes a branch: runs the tests, offers to merge locally, open a pull request or keep it as is, reruns the tests after a merge and removes its own worktree, and discards work only after you type "discard". Use when the implementation is done.

Receiving code review

Checks each review comment against the code before changing anything, clears up every unclear item first, pushes back with technical reasons and never performs agreement. Use when working through review feedback without blind fixes.

Requesting code review

Hands finished work to a fresh reviewer subagent through a template: the commit range, the plan or requirements, findings by severity and a verdict on merging. Use when a task or feature is done and a merge to main is next.

Subagent-driven development

Executes a plan through subagents: a fresh implementer and reviewer for every task, checking spec compliance and code quality, up to five fix rounds and a final review of the whole branch. Use for a plan of independent tasks when each one needs a review.

Systematic debugging

Keeps the agent from guessing at fixes: reproduce the bug and find the root cause first, test one hypothesis at a time, fix with a failing test, and question the design after three failed fixes. Use for any bug, test failure or unexpected behavior.

Test-driven development, Superpowers style

Drives work test-first: a test seen failing, then the least code that passes and a run of the whole suite; code written before its test is deleted. Use for features and bug fixes when the agent tends to add tests after the code.

Using git worktrees

Moves feature work into an isolated git worktree: checks whether the agent is already isolated, prefers the harness's own worktree tool, keeps the folder git-ignored, installs dependencies and runs a baseline test. Use when the work must not land on the branch you have open.

Verification before completion

Stops the agent from saying "done" or "tests pass" until it has rerun the check and read the whole output. Use whenever the agent reports success, commits or opens a pull request.

Writing implementation plans

Turns a spec into a plan for an implementer new to the codebase: files, signatures, interfaces between tasks, tests with exact values and TDD steps with each command's expected output. Use for a multi-step task when the spec is ready and no code exists yet.