Guide · Agent skill
How to use the diagnosing-superpowers agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
diagnosing-superpowers is an agent skill for the superpowers framework. When an AI coding session goes wrong, it makes the agent read the saved session transcript on disk and report what happened, citing the exact file and line number for every finding. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before sharing any output.
Diagnosing Superpowers SessionsjnMetaCode/superpowers-zh · MIT Download the skill Quick start
- 1Download the ZIP. Download the ZIP for skills/diagnosing-superpowers from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Describe the problem. Ask in plain words, for example that a session was slow or ignored the plan, and name the session.
- 5Answer the agent's questions. The agent asks one question at a time to define the problem before it analyses anything.
- 6Review the report. Read the saved report and check that each finding has a file path and line number.
- 7Decide on sharing. Only ask for a bundle if needed, review the redaction log and each file, then approve archiving.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and supporting files that an AI agent loads when a request matches the skill's description. This one is for sessions that went wrong: repeated work, ignored plans, slow or expensive runs, or a skill that never triggered.
The agent reads the session transcript from disk and reports what happened. Each finding must cite a path and line number; findings without a citation are discarded. The skill runs seven parallel analyst sub-agents, each covering one dimension such as plan adherence, repeated work, cost and time, or quality evidence, and then writes a structured report.
- It is report-only. It does not diagnose or change the superpowers skills themselves.
- It can search GitHub issues or prepare a redacted bundle for maintainers, but only with your approval at each gate.
- It works on the current session or on a past session you identify by id or path, with any tool.
Install the diagnosing-superpowers skill
Download the ZIP for skills/diagnosing-superpowers from this page and unzip it. Put the resulting folder in one of two places: ~/.claude/skills/ for all your projects, or a project's .claude/skills/ folder for one project.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check what it needs before you start
The skill needs access to local session transcript files on disk, and your host agent must support sub-agents. Both are required for the full workflow.
gh (the GitHub CLI) is optional and only needed for searching and creating issues. zip or tar is used to archive bundles. The skill runs scripts and uses the network.
- Local session transcript files on disk (required)
- Sub-agent support in the host agent (required)
- gh (GitHub CLI), optional, for issue search and creation
- zip or tar, for archiving bundles
Trigger the skill with a natural request
You do not need a special command. Describe the problem in your own words, and the skill matches requests about a superpowers session that went wrong. The source names examples such as repeated work, ignored plans, a skill that did not trigger, "it's too slow", "why is this so expensive" and "what is it actually doing".
The skill begins by asking you one question at a time until it can state the problem. Be specific about which session, roughly which turns, what you expected and what happened. "It's too slow" is a complaint, not a problem statement, so expect a follow-up question.
- Say which session: the current one, or a past one by id or path.
- Name what you expected and what happened instead.
- Name what you measure: time, tokens, a repeated action, or one specific action.
- For a "what is it doing now" question, the skill reports on a run that is still in progress.
Example requests and which part of the report they use
The skill reads different sections first depending on your complaint. The source gives this mapping, and all seven analysts still run every time.
- "It's too slow": cost-and-time and stumbles are read first.
- "Why did it do extra work?": repeated-work and plan-adherence.
- "Why is this so expensive?": cost-and-time.
- "What is it actually doing?" (still running): skill-timeline, with a note that the run is ongoing.
- "It ignored the plan": plan-adherence, starting with the line where compaction happened.
- "Skill X never triggered": skill-timeline.
Review the output and handle sharing safely
The report is saved to a workspace folder under ~/.superpowers/diagnosing-superpowers/ with a session id, and the skill tells you the path. Transcripts can contain secrets or personal data, and redaction may miss items. If you create an archive for maintainers, the skill shows you the redaction log and file list first, and only archives after you approve.
Before sharing any file, open it and check it yourself. The skill does not publish anything on its own.
- The skill never archives without your approval of the redaction log and file list.
- It never creates a GitHub issue or comment without approval of the exact text.
- Redaction can miss items, so review each file before sharing.
What people use it for
- Finding out why a session took much longer than expected, using timing and the largest tool results.
- Checking whether an agent followed the plan it agreed with you, and where it drifted after a compaction event.
- Spotting repeated tool calls that did the same work twice in one session.
- Preparing a structured, evidence-backed bug report for superpowers maintainers, with a redacted bundle they can review.
- Comparing a new session to earlier ones with the same symptom, after the findings are confirmed.
Frequently asked questions
How do I install the diagnosing-superpowers skill?
Download the ZIP for skills/diagnosing-superpowers from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What does diagnosing-superpowers need to run?
It needs access to local session transcript files on disk and sub-agent support in the host agent. gh (GitHub CLI) is optional, for searching and creating issues, and zip or tar is used for archiving bundles. The skill runs scripts and uses the network.
Is diagnosing-superpowers free, and what is its licence?
The skill is licensed under MIT, as stated in its source. This page does not state pricing for it, so check the source before assuming anything beyond the licence.
Can the skill fix bugs in superpowers for me?
No. It is explicitly report-only. It reports evidence, and triage is left to the people who receive the report, so it does not propose or make changes to superpowers.
Is it safe to share the session data it produces?
Not without review. Transcripts can contain secrets or personal data, and redaction may miss items, so you must check each file yourself before sharing.
What should I do if the skill does not trigger?
Describe the session problem in plain words and name the session by id or path. The skill matches requests about a superpowers session that went wrong, so a vague request may need a follow-up question before it starts.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use diagnosing-superpowers if you want an evidence-backed explanation of why an agent session was slow, costly or off-plan, or if you maintain superpowers and need a structured bug report. Pick something else if you want the agent to fix or change the superpowers skills, or if you need to share session data publicly without a careful manual review.
Download the skill