writing-skills

An agent skill by obra, from obra/superpowers. Tags: api, developer-tools, documents.

What it does

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add obra/superpowers --skill writing-skills

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/obra/superpowers
cp -r superpowers/skills/writing-skills ~/.claude/skills/writing-skills

Safety box score

Grade C, moderate risk: 33 of 100 risk points, rated 2026-10-18. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This skill is mostly documentation and skill-authoring guidance, but it ships a Node helper that executes Graphviz and writes diagram files into a chosen skill directory. The main risks are local command execution, bounded file writes, an install step for Graphviz, and prompt-shaping content that can strongly steer an agent while authoring or testing skills.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	2 (moderate)	`render-graphs.js` runs an external command with `execFileSync('dot', ['-Tsvg'], ...)`, so using the helper executes local code via Graphviz.
Network access	0 (none)	The shipped files do not download data or send it to remote hosts; the URLs in markdown are references only.
Filesystem reach	2 (moderate)	The helper writes `diagrams/*.svg` and `.dot` files under the chosen skill directory (`fs.writeFileSync(...)`), and the docs point agents at `~/.claude/skills/` in the home folder.
Secrets & credentials	0 (none)	Nothing here reads or requests API keys, passwords, tokens, keychains, or browser sessions.
Privilege & persistence	2 (moderate)	`render-graphs.js` expects Graphviz to be installed and prints `brew install graphviz` / `apt install graphviz`, which is an extra package-install step.
Instruction hijack surface	1 (low)	The skill contains heavy prompt-shaping and system-prompt language like `injected into the system prompt` and `IMPORTANT: This is a real scenario. Choose and act.`, but it does not ask the agent to ignore higher-level rules or fetch remote instructions.
Irreversible actions	1 (low)	The checklist includes external publication steps such as `Commit skill to git and push to your fork (if configured)`, but these are optional and not automatic.
Transparency	0 (none)	All bundled logic is readable markdown and JavaScript; there are no binaries, base64 blobs, or unreviewable installers.

Before installing

Read `render-graphs.js`; it shells out to `dot` and writes into `diagrams/`.
Confirm you are okay with the skill docs referring to `~/.claude/skills/` in your home directory.
If you will use the diagram helper, verify Graphviz is already installed or acceptable to add.
Avoid running the helper on an untrusted `SKILL.md` until you have reviewed its `dot` blocks.

Rated 2026-10-18 by an automated review of 6 files from the skill's repository.

Source

Repository: obra/superpowers (all skills from this repository)
Path: skills/writing-skills/SKILL.md
Branch: main
Updated: 2026-09-19

code-documenter — Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides.
deprecation-and-migration — Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another.
documentation-and-adrs — Records decisions and documentation.
intended-vs-implemented — The method for finding the gap between what a system is supposed to do and what the code actually does — the class of bug generic scanners miss because they.
shipping-artifacts — The durable documentation set that makes an AI-built (vibe-coded) app reviewable before shipping.
source-driven-development — Grounds every implementation decision in official documentation.