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.
writing-skills- Author
- Jesse Vincent
- 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 pickwriting-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.
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.
AnyModel