Agent skill · Jesse Vincent (obra)
Writing Skills skill for Claude Code, Codex and Cursor
Communityname: writing-skills★ 305k (repo)pushed 2026-10-23MITSKILL.md on GitHubchecked 2026-11-07
What it does, in the publisher's words
Use when creating new skills, editing existing skills, or verifying skills work before deployment
The description field of the SKILL.md. The agent reads only this at startup and decides from it when to load the full skill.
Install Writing Skills
The skills CLI copies the skill into the folder of each agent you pick (Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf...). Add -g for all projects. Needs Node.js 22.20+. docs
npx skills add obra/superpowers --skill writing-skills
This repo is a plugin marketplace. Inside Claude Code, add it and install the plugin that holds the skill (superpowers), or copy only this skill into ~/.claude/skills. docs
/plugin marketplace add obra/superpowers /plugin install <plugin>@superpowers-dev # or only this skill: npx skills add obra/superpowers --skill writing-skills -a claude-code
Download the skill folder, zip it, then Customize > Skills > + > Create skill > Upload a skill. Code execution must be on (Settings > Capabilities). docs
git clone --depth 1 https://github.com/obra/superpowers.git /tmp/writing-skills-src cp -r /tmp/writing-skills-src/skills/writing-skills ./writing-skills zip -r writing-skills.zip writing-skills
Codex reads skills from .agents/skills in the repo or ~/.agents/skills. Type $ in Codex to use one. docs
npx skills add obra/superpowers --skill writing-skills -a codex
gh skill (GitHub CLI 2.90+, preview) installs it for Copilot in VS Code, the CLI and the cloud agent. Copilot also reads .github/skills and ~/.copilot/skills. docs
gh skill install obra/superpowers writing-skills
Cursor reads .cursor/skills, .agents/skills and ~/.cursor/skills (and .claude/skills). It does not install loose skills from a GitHub URL, so copy it in. docs
npx skills add obra/superpowers --skill writing-skills -a cursor
Installs from the GitHub repo; --path picks this skill out of the repo. Default scope is user (all projects). docs
gemini skills install https://github.com/obra/superpowers.git --path skills/writing-skills
OpenCode reads .opencode/skills, ~/.config/opencode/skills and the Claude and .agents folders. docs
npx skills add obra/superpowers --skill writing-skills -a opencode
Windsurf (now Devin Desktop) reads .devin/skills, .windsurf/skills and ~/.codeium/windsurf/skills. docs
npx skills add obra/superpowers --skill writing-skills -a windsurf
Works with
Claude Code, Claude.ai and Claude Desktop, Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Windsurf and other agents that read the open Agent Skills format.
- Bundles 1 JavaScript script the agent can run, so it needs JavaScript on the machine. In the Claude apps, code execution must be on.
What's in the SKILL.md
- Overview
- What is a Skill?
- TDD Mapping for Skills
- When to Create a Skill
- Skill Types
- Technique
- Pattern
- Reference
- Directory Structure
- Writing SKILL.md
- Flowcharts
- Code Examples
- File Organization
- Self-Contained Skill
- Skill with Reusable Tool
- Skill with Heavy Reference
- The Iron Law (Same as TDD)
- Testing All Skill Types
- Discipline-Enforcing Skills (rules/requirements)
- Technique Skills (how-to guides)
- Pattern Skills (mental models)
- Reference Skills (documentation/APIs)
- Common Rationalizations for Skipping Testing
- Match the Form to the Failure
- + 14 more
Bundled files
- references/CLAUDE_MD_TESTING.md
- references/anthropic-best-practices.md
- references/bulletproofing.md
- references/discovery.md
- references/flowcharts.md
- references/graphviz-conventions.dot
- references/persuasion-principles.md
- references/testing-skills-with-subagents.md
- render-graphs.js
Loaded only when the instructions point to them.
Facts
- Skill name
- writing-skills
- Publisher
- Jesse Vincent (obra) (community)
- Repo
- obra/superpowers
- License
- MIT
- SKILL.md size
- 2,314 words, 395 lines
- Bundled files
- 9, 1 scripts (JavaScript), 7 docs
- Repo stars
- 305k (as of 2026-10-24)
- SKILL.md checked
- 2026-11-07
More skills from obra/superpowers
- Brainstorming: Makes the agent clarify goals and explore options with you before building anything new.
- Requesting Code Review: Has the agent get its finished work reviewed against requirements before merging.
- Subagent-Driven Development: Executes a plan by handing each task to a fresh subagent with review between steps.
- Systematic Debugging: A root-cause-first process for bugs and failing tests before any fix is attempted.
- Test-Driven Development: Enforces a red-green-refactor loop: write a failing test first, then the code.
- Using Git Worktrees: Sets up an isolated git worktree before feature work so the main checkout stays clean.
- Verification Before Completion: Requires running checks and showing their output before claiming work is done.
- Writing Plans: Turns a spec into a detailed, step-by-step implementation plan before coding starts.
Related workflow & planning skills
- Skill Creator · Anthropic
- GitHub: Address PR Comments · OpenAI
- Skill Installer (Codex) · OpenAI
- Modern Python Tooling · Trail of Bits
- Commit (Sentry style) · Sentry
- Notion Spec to Implementation · Notion
- Git Commit · GitHub (community contributions)
FAQ
What does the writing-skills skill do?+
Method for writing and testing new skills so they trigger and behave reliably. In its own SKILL.md, Jesse Vincent (obra) describes it as: "Use when creating new skills, editing existing skills, or verifying skills work before deployment"
How do I install the writing-skills skill?+
Run npx skills add obra/superpowers --skill writing-skills and pick your agents, or use the tab for your agent above. In Claude Code the skill ends up in ~/.claude/skills/writing-skills/SKILL.md; in Codex and Cursor in .agents/skills/writing-skills/.
Does Writing Skills work in Codex, Cursor and Copilot, or only Claude?+
It's a standard SKILL.md, so any agent that reads the Agent Skills format can use it: Claude Code, the Claude apps, Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Windsurf and more.
Who maintains Writing Skills?+
Jesse Vincent (obra) (a community project), in the obra/superpowers repo on GitHub, last pushed 2026-10-23. License: MIT.
Read a skill's SKILL.md and scripts before you install it: skills aren't verified by any agent vendor. Claude skills marketplace · How to install skills · MCP servers