Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 24 October 2026
What is the diagnosing-superpowers skill?
diagnosing-superpowers is a Superpowers skill that works out why an agent session went wrong: it asks you what you expected, reads the session transcripts on disk, and reports what happened with a file and line citation for every finding. It is built for sessions that repeated work, ignored a plan, ran long, cost too much, or where a skill didn't fire.
It ships in obra/superpowers, the skills library by Jesse Vincent and Prime Radiant, and is one of its newest skills: its skills.sh page first saw it on 19 September 2026 and listed 20.1K installs (snapshot, 24 October 2026).
Its core principle, from the SKILL.md: "Every finding cites path:line. No citation, no finding." Every number must come from the transcript or a command the agent ran, never from memory.
The skill is clear about its role: "You report; you do not diagnose superpowers." Whoever triages the report decides whether Superpowers changes.
What does it do?
The workflow has seven steps. The agent creates a todo for each, and the last three run only when their condition is met.
- Problem intake. It asks one question at a time until it can write a problem statement: which sessions, which turns, what you expected, what happened, and the measure you care about (wall-clock time, tokens, repeated actions). "It took too long" counts as a complaint, not a problem statement.
- Locate. It resolves each session to verified absolute paths, confirms a past session by quoting its first prompt and timestamp, lists subagent transcripts, and creates a workspace at
~/.superpowers/diagnosing-superpowers/<session-id>/. - Triage. It reads the region around the problem itself, then dispatches one analyst subagent per dimension in parallel. The seven dimensions are skill timeline, plan adherence, repeated work, stumbles, quality evidence, request conflicts, and cost and time. Findings without a
path:lineare discarded. - Report. It fills a fixed report template, writes it to the workspace and shows it to you.
- GitHub issues. When the report says Superpowers involvement is possible or likely, or you ask, it searches open and closed issues for matches. If none match, it drafts an issue and creates it only after you approve the text.
- Export. Only on request, it builds a bundle at a redaction level you choose (skeleton, evidence or full), scrubs it, audits the scrub, and repeats until the audit comes back clean.
- Similar sessions. On request, it turns confirmed findings into a signature and checks other sessions for the same pattern.
What does the report contain?
The template in templates/report.md has these sections: problem statement, triage verdict, environment, sessions examined, timeline, findings (one subsection per dimension, plus other plugins and skills used), Superpowers involvement, coverage notes, and similar sessions when requested. The involvement section takes one of three values, "not indicated | possible | likely", and "does not name a defect and does not propose a change."
What's in the folder?
| Folder | Contents |
|---|---|
prompts/ |
One brief per analyst dimension, a shared analyst brief, scrub and scrub-audit briefs, and a similar-session brief |
references/ |
Context safety, session discovery, GitHub issue search and the redaction policy |
templates/ |
Case file, report, issue and bundle README |
The redaction policy replaces emails, people's names, account ids, secrets, private hosts, home paths, private repository names and terms you mark as proprietary with placeholders such as <SECRET-n>. It keeps session ids, tool and skill names, model ids and line numbers, because the bundle is "useless without them."
How do you install it?
It comes with the Superpowers plugin, so if you already run Superpowers you have it.
Claude Code. From the README:
/plugin install superpowers@claude-plugins-official
Or through the Superpowers marketplace:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
Per Claude Code's plugin docs, plugin skills appear as /<plugin>:<skill>, so this one is /superpowers:diagnosing-superpowers.
Codex, Cursor and others. The README has install steps for 16 harnesses, including Codex (/plugins, search for Superpowers) and Cursor (/add-plugin superpowers). See Codex skills and Cursor skills for how each finds skills.
Just this skill. The skills CLI can copy the folder on its own:
npx skills add https://github.com/obra/superpowers --skill diagnosing-superpowers
The skill dispatches analyst subagents, so your agent needs subagent support. Step 5 uses the gh CLI for issue search and creation.
How do you use it?
The README's trigger is to ask your agent to "figure out what went wrong with superpowers in this session." For an earlier session, name it by id. Example prompts (suggestions, except the first, which is the README's wording):
Figure out what went wrong with superpowers in this session.Figure out what went wrong with superpowers in session <id>. It ignored the plan after the third task.Why did the brainstorming skill never fire when I asked for a new feature yesterday?This run took two hours for a small change. Find out where the time went.Build a bug report for the Superpowers maintainers from this session.
Expect questions first. The skill's rules say nothing past intake starts until you answer, and if you're away it writes the questions and stops. A specific request, such as one event or what is running right now, counts as its own problem statement.
The quick-reference table maps complaints to where it reads first. "It took too long" leads with cost-and-time and stumbles; "It ignored the plan" leads with plan adherence, reading compaction lines first; "Skill X never fired" leads with the skill timeline.
Tips and limits
- It is slow and thorough by design. All seven analysts always run, and long transcripts get split by turn range. Expect a diagnosis to use real tokens; see our Claude Code cost guide for how to track usage.
- Transcripts can be huge. The context-safety rules tell every reader to measure a file before reading it and never to print whole records, since "One transcript line can be a megabyte."
- No advice, no fixes. Even if you press for a fix, the skill points you to the issue step instead. Use systematic-debugging when the problem is in your own code.
- Review bundles yourself. The skill says scrubbing can miss things and that you must review every file before sharing.
- Security audit. On 24 October 2026, the skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass and Snyk: Warn. The page gave no details for the Warn. The skill reads session files on your machine and can run
gh,ziportarat your request.
Save it in your Kipt library
The MIT License allows copies as long as you keep the copyright notice. In Kipt, open Skills and paste the folder's GitHub link; Kipt reads the SKILL.md along with its prompts/, references/ and templates/ files, and for a repo with many skills it shows a list to pick from. Your library lives as Markdown in a private GitHub repo you own and installs into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Jesse Vincent, Prime Radiant or obra/superpowers.
Similar skills
- using-superpowers skill: the bootstrap whose behavior the skill timeline traces.
- Superpowers skills: the full library and workflow.
- Systematic debugging skill: root-cause debugging for your code rather than the agent's session.
- Verification before completion skill: evidence before "done", the same instinct applied to the agent's own work.
- Dispatching parallel agents skill: the pattern diagnosing-superpowers uses for its analysts.