Writing Skills (Authoring & Testing Skills)
Applies TDD's red-green-refactor to writing skill documentation itself — expose real failure modes with a no-skill baseline test first, then write targeted guidance instead of guessing
It provides substantial practical value for creating, editing, and pre-deployment verification of agent Skills through TDD mapping, structure guidance, discovery optimization, testing categories, and anti-rationalization techniques. It targets Skill authors and maintainers and defines some boundaries, including technique, pattern, and reference Skills. However, it is primarily methodology and lacks minimal executable examples and sharper limits for different runtimes.
The process is structured and sequential: RED baseline testing, minimal GREEN implementation, then REFACTOR and re-verification. Reliability is limited because the selected Skill supplies no directly runnable test implementation, pinned test environment, model-matrix results, or failure-recovery procedure. It also depends on the separately named superpowers:test-driven-development Skill, whose availability and behavior are not established by this file.
The Skill is primarily documentary and does not itself request network access, credentials, exfiltration, or elevated permissions. A significant safety gap is the repeated mandatory instruction to ‘Delete it’ and start over when code was written before tests, without backup, recovery, user confirmation, or protection for uncommitted work. The ‘No exceptions’ framing can cause avoidable data loss. The likely external effect is limited to the agent workspace, but the instruction still warrants caution.
The material includes a TDD mapping, pressure-scenario examples, success criteria, and checklists, providing some traceability. Major gaps remain: there are no actual RED/GREEN/REFACTOR execution logs, model or version details, raw pass-rate data, or independent review results. Claims such as ‘100% compliance’ appear as illustrative or historical statements and cannot be confirmed from static evidence. The cited research and official guidance were not independently verified here.
The directory guidance, frontmatter rules, file-splitting advice, reference depth guidance, quick references, and scenario templates are useful. Adoption cost is high because users must understand the separate TDD Skill, provide subagents or API access, and establish baselines themselves. Inputs, outputs, cross-model compatibility, troubleshooting, and clear exit criteria are not fully specified. The frontmatter description also summarizes workflow, contrary to the Skill's own rule that descriptions should contain triggering conditions only.
The repository materials show an MIT license and package.json version 6.1.1, while the README supplies contribution, testing, and update information. The selected Skill has no own version, changelog, release owner, compatibility matrix, or explicit per-Skill update path. The publisher is not verified by the FollowSkills enterprise registry, so identity or brand cannot support governance or reliability claims.
- Do not apply the ‘delete code’ rule without backup or confirmation; limit it to recoverable uncommitted work and provide a recovery path.
- Run and record baseline, GREEN, REFACTOR, and multi-model tests before deployment; the supplied material does not prove they were completed.
- Confirm that superpowers:test-driven-development and the referenced supporting files are available in the target runtime, or the workflow may not start.
- Revise the description so it contains triggering conditions only and does not summarize the workflow in metadata.
What it does & when to use it
The longest doc in the set (689 lines) and the only "skill for writing skills." The core analogy: the skill document is production code, pressure-test scenarios are test cases, an agent violating the rule without the skill is RED, complying once the skill is added is GREEN, finding a new loophole and patching it is REFACTOR. It requires running a baseline test — no skill present, observe what the agent naturally does — before writing anything, recording the actual rationalization phrases it produces verbatim, and writing targeted counters for those specific phrases instead of guessing in advance how an agent might try to cut corners.
First judges whether a technique is worth turning into a skill (not a one-off, will be reused, broadly applicable). The description field must only state when to use it, never how — the doc cites a tested case: once a description summarizes the workflow, the agent follows the description as a shortcut and skips reading the skill body's detailed steps. Gives concrete directory-structure conventions, SDO (Skill Discovery Optimization) techniques so future agents can find the skill, and token-efficiency targets (frequently-loaded skills capped at 150-200 words). The core RED-GREEN-REFACTOR loop requires running pressure-scenario baseline tests first, recording the original rationalizations verbatim, writing minimal targeted documentation, then re-testing to confirm compliance. Also gives a problem-type → documentation-form table (a "knows the rule, breaks it anyway" problem needs a prohibition + rationalization table; a "complies but wrong-shaped output" problem needs a positive template, not a prohibition list — using the wrong form measurably performs worse in testing).
- A technique or lesson seems worth preserving — deciding whether it's worth a dedicated new skill versus just going in the project's own instructions file
- A skill document already exists, but under pressure (time pressure, sunk cost) the agent still routes around the rule — needs a RED-GREEN-REFACTOR pass to close the loophole
- Writing a skill's description field, avoiding a workflow-summary description that would let a future agent take a shortcut and skip reading the full document
Pros & cons
- The "run a no-skill baseline test, record the real rationalizations" methodology is the most valuable part of this skill — it avoids imagining how an agent might cut corners and instead documents observed real behavior
- The "problem type determines documentation form" table cites test evidence (noting that prohibition-style wording sometimes measurably performed worse than giving no guidance at all in certain scenarios) — considerably more persuasive than generic writing advice
- The rule that description fields must state only triggering conditions, never a workflow summary, comes with a specific reproduced failure case rather than an abstract assertion
- Only reliably self-enforcing on harnesses that actually read and follow SKILL.md instructions (Claude Code, Codex CLI, etc.) — in a plain chat interface it's just a document a human has to apply by hand.
- At 689 lines, the longest doc in the set, and it calls for dispatching subagents to run multiple rounds of pressure testing — itself a real resource investment, raising the bar for an individual or small team to adopt
- The methodology assumes you can dispatch pressure-test subagents at scale to verify a document's effect; without subagent-dispatch capability, the RED-GREEN-REFACTOR loop is hard to actually execute and degrades into writing from experience alone
How to install
Installed as part of the obra/superpowers plugin — individual skills can't be installed standalone:
- Claude Code: official marketplace
/plugin install superpowers@claude-plugins-official; or register the community marketplace with/plugin marketplace add obra/superpowers-marketplacethen/plugin install superpowers@superpowers-marketplace - Also supports Antigravity, Codex App/CLI, Cursor, Factory Droid, GitHub Copilot CLI, Kimi Code, OpenCode, and Pi — see the repo README for the exact command per harness
Once installed, this skill activates alongside the other 13 Superpowers skills, auto-triggered by using-superpowers based on context — there's no separate invocation step.
How to use
Triggers when creating a new skill, editing an existing one, or wanting to verify a skill actually works before relying on it. Requires understanding the test-driven-development skill first, since the whole methodology is a direct port of it.
Compared to similar skills
Compared to writing a SKILL.md from experience with no verification, this skill provides an actionable verification method (baseline test → record real failure modes → targeted documentation → re-test) that in principle meaningfully lowers the risk of shipping guidance that doesn't actually work. Unlike the other 13 Superpowers skills, which target concrete development steps, this one operates at a meta level — it teaches you how to write the others well, and has limited standalone value outside the Superpowers system.