How to use the Diagnosing Superpowers agent skill

What the skill makes the agent do

When you invoke the skill, the agent first asks you questions, one at a time, until it can state the session or sessions involved, what you expected, what happened, and what you want to measure, such as wall-clock time, tokens, repeated actions or one specific action. It then locates the saved session transcripts on disk and runs parallel analyses across several dimensions: skill timeline, plan adherence, repeated work, stumbles, quality evidence, request conflicts, and cost and time.

The output is a written report. Every finding cites a specific path and line in the transcript, so you can check the evidence yourself. The skill states that it reports evidence and does not diagnose superpowers or propose changes to skills.

Install the diagnosing-superpowers skill

Download the ZIP for this skill from this page and unzip it. For a personal install, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you start

The skill needs access to local session transcript files on disk, and Superpowers installed in a harness that reads SKILL.md files. It runs scripts and uses the network. GitHub CLI (gh) is optional and is only needed for searching and creating GitHub issues. zip or tar is optional and is only needed to create an archive of a bundle.

• Access to local session transcript files on disk
• Superpowers installed and a SKILL.md-capable agent harness
• Optional: GitHub CLI (gh) for searching and creating issues
• Optional: zip or tar for creating archives

Trigger the skill with a natural request

You do not need a special command. Describe the problem in your own words and the agent will match the request to the skill. The skill's description lists examples such as repeated work, ignored plans, stumbles, a skill that didn't fire, "it took too long", "why is it so expensive" and "what is it doing".

Name the session if you can. The skill works on the current session or a past one identified by id or path. Be specific about one event where possible, because a whole-session "why" is treated as a complaint that needs narrowing.

• "My last session took too long. Find out why."
• "Why did the agent redo the migration work it had already finished?"
• "Why is this session so expensive? Use the transcript."
• "A skill never fired in that session. Check what happened."
• "Build a bug report for the superpowers maintainers from session abc123."

Work through the intake and the report

Expect the agent to ask clarifying questions before any analysis starts, and to tell you the folder where it keeps its working files. Once analysis finishes, it writes a report to the workspace, shows it to you, and gives you the path.

If the report says a superpowers issue is possible or likely, the agent can search open and closed GitHub issues for matching symptoms and suggest adding the report to the closest one. It only creates an issue after you approve the exact text.

Build a scrubbed bug-report bundle only when you ask

The skill can prepare a bundle for the superpowers maintainers, but it does not build one unprompted. When you ask, it asks which redaction level you want: skeleton (no tool-result bodies), evidence (bodies only for cited events), or full. It then runs a scrub and an audit, repeating until the audit is clean, and shows you the scrub log and file list before any archive is made.

Transcripts can contain secrets or private content, and scrubbing can miss things. Review every file before you share it.

• Skeleton: no tool-result bodies
• Evidence: bodies only for cited events
• Full: complete content