troubleshoot — Claude Code skill: what it does, how to install
Stops agents from blindly retrying failed commands and enforces systematic root cause analysis on errors.
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a claude-codeWhat troubleshoot does
When an AI coding agent hits a runtime error, its default reaction is often to run the exact same command again. The troubleshoot skill halts this loop. It forces an eight-step diagnosis process: stop immediately, observe the failure, build two or three hypotheses, inspect logs or configs, pinpoint the core defect, apply a fix, verify it, and record the lesson.
The rule explicitly bans common shortcuts. Raising timeouts without investigating latency or ignoring compiler warnings because the build passed are prohibited. Every investigation ends with a strict Root Cause Analysis summary that documents the exact error, the actual cause, the remediation, and steps to prevent recurrence.
What it helps with
- stop repetitive command retries after agent errors
- diagnose stack traces and runtime crashes systematically
- identify root causes instead of masking warning symptoms
- generate structured post-mortem summaries for bugs
Example prompts for the agent
- Use
troubleshootto investigate why the migration script crashed. - Analyze this timeout error and find the root cause.
- Follow the troubleshooting protocol to fix the broken test suite.
How to install troubleshoot
1Skills CLI (Vercel)
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a claude-code2Manually: put the files in place
~/.claude/skills/troubleshoot/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/troubleshoot/
1Skills CLI (Vercel)
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a codex2Manually: put the files in place
.agents/skills/troubleshoot/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a cursor2Manually: put the files in place
.cursor/skills/troubleshoot/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SuperClaude-Org/SuperClaude_Framework troubleshoot2Manually: put the files in place
.github/skills/troubleshoot/SKILL.md1Skills CLI (Vercel)
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a gemini-cli2Platform CLI
gemini skills install https://github.com/SuperClaude-Org/SuperClaude_Framework --path plugins/superclaude/skills/troubleshootManually: put the files in place
.devin/skills/troubleshoot/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about troubleshoot
How to install troubleshoot in Claude Code?
Run npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a claude-code in your terminal. Alternatively, place the file directly at ~/.claude/skills/troubleshoot/SKILL.md.
What does the troubleshoot skill do?
It establishes an eight-step troubleshooting protocol for AI agents. The agent stops repeated commands, inspects logs, formulates hypotheses, and addresses the underlying defect before writing a fix.
What anti-patterns does the protocol prohibit?
It strictly forbids blind retries, bumping timeout thresholds without investigating causes, and ignoring warnings as future technical debt.
Source text
SKILL.md · MIT
--- name: troubleshoot description: Systematic troubleshooting with root cause analysis. Use when users report errors, bugs, or unexpected behavior. Never retry without understanding why. --- # Troubleshooting Protocol Follow this systematic root cause analysis process. NEVER retry the same approach without understanding WHY it failed. ## Protocol 1. **STOP**: Do not re-execute the same command 2. **Observe**: What exactly happened? What was expected? 3. **Hypothesize**: What could cause this? (list 2-3 possibilities) 4. **Investigate**: Check official docs, logs, stack traces, config 5. **Root Cause**: Identify the fundamental cause (not symptoms) 6. **Fix**: Implement a solution that addresses the root cause 7. **Verify**: Confirm the fix works 8. **Learn**: Document the solution for future reference ## Anti-Patterns (strictly prohibited) - "Got an error. Let's just try again" - "Retry: attempt 1... attempt 2... attempt 3..." - "It timed out, so let's increase the wait time" (ignoring root cause) - "There are warnings but it works, so it's fine" (future technical debt) ## Required Format ``` ## Root Cause Analysis **Error**: [Exact error message] **Expected**: [What should have happened] **Cause**: [Root cause with evidence] **Fix**: [Solution addressing root cause] **Prevention**: [How to prevent recurrence] ``` Apply this to: $ARGUMENTS
© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework
