Writing Skills
Create, edit, and evaluate SKILL.md instructions with the Superpowers test-driven approach: observe a baseline failure, revise the skill, and rerun the scenario.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Writing Skills when creating a new skill, editing existing instructions, or checking that a skill changes agent behavior. Its Superpowers workflow applies failing and passing scenario tests to skill authoring.
When not to use it
A missing installation or dependency is not necessarily an instruction-writing problem. Check setup first. If you have no representative scenarios or way to observe agent behavior, treat the rewrite as a draft rather than a verified improvement.
How to install
Where will you use it?
Install the publisher’s plugin
This installs a bundle that can include other skills. Choose this method or the manual alternative below; you only need one installation.
Run these commands in Claude Code:
Claude Code CLI/plugin install superpowers@claude-plugins-official
- Ask Claude Code to use Writing Skills on a small task and confirm that it loads. Check the setup requirements in the publisher’s guide if it cannot run.
Alternative: install the folder manually
Use these steps if you choose the manual folder method. If you installed the plugin above, skip this alternative.
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/writing-skills/SKILL.md. For a shared project, commit the folder at .claude/skills/writing-skills/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 69/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 88/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- geminiinferred
The skill text mentions Gemini or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- copilotinferred
The skill text mentions Copilot or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
Try one small task
Best first exercise: reproduce a skill failure, then revise its instructions against that case.
See actual outputs and execution limits →What you need
- The Superpowers package and a working understanding of its test-driven-development skill.
- A draft skill plus concrete scenarios that expose an instruction or trigger failure.
Improve a meeting-action skill that invents missing owners.
Use writing-skills to improve my meeting-actions SKILL.md. Reproduce its behavior on notes with an unnamed owner before editing. Require unknown instead of a guessed owner. Include an unrelated-request case. Make the smallest instruction change, rerun the cases, and preserve baseline and revised outputs. If execution is unavailable, provide the test plan and explicitly say it has not run.
Expected result
A specification to check against, not output from an AI run.
A revised skill with a baseline/revised comparison, or an explicitly unexecuted evaluation plan.
- The report identifies the observed failure instead of assuming that a rewrite improved anything.
- The revised skill preserves missing fields and does not broaden its trigger to unrelated tasks.
- Saved outputs identify which skill version produced them.
Where this exercise stops
- This is a Superpowers skill from obra, not an Anthropic-authored skill.
- Passing a few examples does not establish general trigger accuracy or cross-agent behavior.
Recorded example run
These files came from actual execution in a Codex session. They were produced and checked within the same session; this is scoped evidence, not independent review or a measured success rate.
Meeting-action instructions: one observed format correction
Executed · Automated Codex exercise
Codex agent; Node.js 24.13.0, Python 3.12.3, Linux 7.0.0-1010-aws. Exact model version not exposed.
A collaborating Codex agent answered a synthetic draft scenario before editing. The evaluator checked the saved response, added one sentence to the draft, then requested the same scenario plus an unrelated recipe from the same agent.
Download the actual outputs
- Run report
- Sources, snapshots and original evidence (ZIP)
- Executed command ledger
- Baseline SKILL.md
- Revised SKILL.md
- Actual baseline response
- Actual revised response
- Comparison provenance
Recorded checks and observations
- Observed: The actual baseline check failed because the unassigned owner was null instead of the requested string unknown.
- Observed: The revised response preserved the two actions and used unknown; its check passed.
- Observed: The revised unrelated recipe returned no meeting actions, and the revised SKILL.md passed structural validation.
Scope, limitations and pinned sources
- The agent read the pinned upstream instructions and used their prescribed tools. Native Claude skill loading and general cross-agent compatibility were not tested.
- The synthetic baseline did not reproduce an invented owner; the observed defect was null versus unknown.
- One baseline and one revised meeting sample shared the overall conversation and responding agent; the comparison was unblinded.
- This is not a fresh-context trial, automatic-selection test, hallucination-reduction result, or general reliability estimate.
- The executor was Codex in this conversation; the exact model version was not exposed.
- These examples do not represent independent human users, customer outcomes or a compatibility certification.
Source and evidence
The upstream instructions informed this guide. The exercise and acceptance checks are an OpxSkills test recipe. Where a run is recorded, its actual outputs, environment and limits appear separately above. A recorded example does not establish general model compatibility or a success rate.
Source reviewed · Upstream revision 8ca22dba9a94
What this skill does
Writing Skills is maintained in the obra/superpowers repository. It applies test-driven development to reusable agent instructions.
Start with a scenario and observe behavior before changing the skill. Then revise the instructions and compare a fresh run with that baseline. It supports both new and existing skills.
Intended uses
- Fix a skill that never triggers
- Shorten a SKILL.md that blows the context window
- Review a teammate skill before merging
Implementation notes
- Descriptions should name synonyms users actually say.
- Link to scripts/templates; do not paste them into SKILL.md.
- Keep baseline and revised run artifacts separate so the improvement can be checked.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.