Skip to main content
Agent skillFirst-run guide

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 started

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.

  1. Run these commands in Claude Code:

    Claude Code CLI
    /plugin install superpowers@claude-plugins-official
  2. 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.

  1. 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.
  2. 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.
  3. 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.

Full install guide for Claude, Cursor, and Codex →

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.

Source reviewedExample execution recorded

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.

First task prompt
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

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.
Read the execution record (JSON) →
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.