Agent skill · Jesse Vincent (obra)

Systematic Debugging skill for Claude Code, Codex and Cursor

A root-cause-first process for bugs and failing tests before any fix is attempted.

Communityname: systematic-debugging★ 305k (repo)pushed 2026-10-23MITSKILL.md on GitHubchecked 2026-11-07

What it does, in the publisher's words

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

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 Systematic Debugging

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 systematic-debugging

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 systematic-debugging -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/systematic-debugging-src
cp -r /tmp/systematic-debugging-src/skills/systematic-debugging ./systematic-debugging
zip -r systematic-debugging.zip systematic-debugging

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 systematic-debugging -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 systematic-debugging

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 systematic-debugging -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/systematic-debugging

OpenCode reads .opencode/skills, ~/.config/opencode/skills and the Claude and .agents folders. docs

npx skills add obra/superpowers --skill systematic-debugging -a opencode

Windsurf (now Devin Desktop) reads .devin/skills, .windsurf/skills and ~/.codeium/windsurf/skills. docs

npx skills add obra/superpowers --skill systematic-debugging -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 2 TypeScript/shell scripts the agent can run, so it needs TypeScript and shell on the machine. In the Claude apps, code execution must be on.

What's in the SKILL.md

14 sections

Overview
The Iron Law
When to Use
The Four Phases
Phase 1: Root Cause Investigation
Phase 2: Pattern Analysis
Phase 3: Hypothesis and Testing
Phase 4: Implementation
Red Flags - STOP and Follow Process
your human partner's Signals You're Doing It Wrong
Common Rationalizations
Quick Reference
When Process Reveals "No Root Cause"
Supporting Techniques

Bundled files

condition-based-waiting-example.ts
condition-based-waiting.md
defense-in-depth.md
find-polluter.sh
root-cause-tracing.md

Loaded only when the instructions point to them.

Facts

Skill name: systematic-debugging
Publisher: Jesse Vincent (obra) (community)
Repo: obra/superpowers
License: MIT
SKILL.md size: 1,300 words, 279 lines
Bundled files: 5, 2 scripts (TypeScript, shell), 3 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.
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.
Writing Skills: Method for writing and testing new skills so they trigger and behave reliably.

Related testing & qa skills

Web App Testing · Anthropic
Agent Browser · Vercel
Playwright Browser Automation · OpenAI
Playwright CLI · Microsoft (Playwright)
Property-Based Testing · Trail of Bits
Analyze .NET Performance · Microsoft (.NET)
Browserbase Browser · Browserbase
Adversarial UI Test · Browserbase

FAQ

What does the systematic-debugging skill do?+

A root-cause-first process for bugs and failing tests before any fix is attempted. In its own SKILL.md, Jesse Vincent (obra) describes it as: "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes"

How do I install the systematic-debugging skill?+

Run npx skills add obra/superpowers --skill systematic-debugging and pick your agents, or use the tab for your agent above. In Claude Code the skill ends up in ~/.claude/skills/systematic-debugging/SKILL.md; in Codex and Cursor in .agents/skills/systematic-debugging/.

Does Systematic Debugging 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 Systematic Debugging?+

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