Debugging and Error Recovery
addyosmani/agent-skills
Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.
Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms.
Install Root Cause Analysis
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install rohitg00/skillkit root-cause-analysis --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .claude/skills/root-cause-analysis && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .claude/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysisType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install rohitg00/skillkit root-cause-analysis --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .agents/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .agents/skills/root-cause-analysis && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .agents/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install rohitg00/skillkit root-cause-analysis --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .cursor/skills/root-cause-analysis && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .cursor/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/rohitg00/skillkit.git --path packages/core/src/methodology/packs/debugging/root-cause-analysis--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install rohitg00/skillkit root-cause-analysis --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .gemini/skills/root-cause-analysis && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .gemini/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install rohitg00/skillkit root-cause-analysisInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .github/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .github/skills/root-cause-analysis && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .github/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add rohitg00/skillkit --skill root-cause-analysis -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install rohitg00/skillkit root-cause-analysis --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/rohitg00/skillkit.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/packages/core/src/methodology/packs/debugging/root-cause-analysis .opencode/skills/root-cause-analysis && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "root-cause-analysis" agent skill from https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/debugging/root-cause-analysis into .opencode/skills/root-cause-analysis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-analysis", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
root-cause-analysis- GitHub stars
- 1.5k
- Token cost
- ~1.4k tokens
- SKILL.md length
- 511 words
- Files
- 1
- Skills in repo
- 14
- Repo updated
- First seen
- Licence
- Apache-2.0
At a glance
Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms.
- Works in 5 steps: Reproduce the Bug → Gather Evidence → Form Hypotheses → …
- A user reports a bug
- SKILL.md covers Core Principle, The Five Whys Method, Investigation Phases and Common Root Cause Categories, plus 4 more sections
- Calls git
What it does
Root Cause Analysis is an agent skill from rohitg00/skillkit. Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and…
Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Root cause analysis and Debugging. It works with Git. The repository describes itself as: Supercharge AI coding agents with portable skills. Install, translate & share skills across Claude Code, Cursor, Codex, Copilot & 40 more. The licence is Apache-2.0.
When your agent uses it
- A user reports a bug
- Broken behavior and needs to debug
- Investigate why something is not working
- Especially for complex
Example prompts
- “Use the root-cause-analysis skill to perform systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior…”
- “/root-cause-analysis”
Workflow steps
5 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit d2e5c34. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Root Cause Analysis loads about 1.4k tokens when it runs. Until then it costs about 155 tokens; SKILL.md has 511 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from rohitg00/skillkit at commit d2e5c34, republished under its Apache-2.0 licence (© rohitg00). 511 words, ~1,352 tokens.
Download SKILL.mdSave it as
.claude/skills/root-cause-analysis/SKILL.md (or your agent's skills folder).- name
- root-cause-analysis
- description
- Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix.
- version
- 1.0.0
- triggers
- root cause, debugging, find the bug, why is this happening, investigate issue, bug investigation
- tags
- debugging, investigation, problem-solving, systematic
- difficulty
- intermediate
- estimatedTime
- 20
- relatedSkills
- debugging/trace-and-isolate, debugging/hypothesis-testing
Root Cause Analysis
You are performing systematic root cause analysis to find the true source of a bug. Do not apply fixes until you understand WHY the bug exists.
Core Principle
Never fix a symptom. Always find and fix the root cause.
The Five Whys Method
Ask "Why?" repeatedly to drill down to the root cause:
- Why did the API return an error? → The database query failed
- Why did the database query fail? → The connection pool was exhausted
- Why was the pool exhausted? → ROOT CAUSE: Missing
finallyblock to close connections
Investigation Phases
Phase 1: Reproduce the Bug
Before investigating:
- Reproduce consistently - If you can't reproduce it, you can't verify a fix
- Document reproduction steps - Exact sequence of actions
- Note environment details - OS, versions, configuration
- Identify minimal reproduction - Smallest case that shows the bug
Questions to answer:
- Does it happen every time or intermittently?
- Does it happen in all environments?
- When did it start happening? (recent changes)
Phase 2: Gather Evidence
Collect information before forming theories:
- Error messages and stack traces
- Log files (application, system, database)
- Recent code changes (git log, blame)
- User reports and reproduction steps
- Monitoring data (metrics, APM)
- Related issues (search issue tracker)
Do NOT:
- Make changes while gathering evidence
- Assume you know the cause without evidence
- Ignore related symptoms
Phase 3: Form Hypotheses
Based on evidence, create ranked hypotheses:
| Priority | Hypothesis | Evidence | Test Plan |
|---|---|---|---|
| 1 | Connection leak in UserService | Stack trace shows connection pool | Add logging, check usage |
| 2 | Query timeout too short | Occurs under load | Test with longer timeout |
| 3 | Database server overload | Correlates with peak hours | Check DB metrics |
For each hypothesis:
- What evidence supports it?
- What evidence contradicts it?
- How can we test it?
Show full SKILL.md (223 more words)Show less
Phase 4: Test Hypotheses
Test each hypothesis systematically:
- Start with highest probability
- Design a definitive test - Should clearly confirm or reject
- Make ONE change at a time
- Document results
If hypothesis is rejected:
- Cross it off the list
- Re-evaluate remaining hypotheses
- Consider if new evidence suggests new hypotheses
Phase 5: Verify Root Cause
Before declaring root cause found:
- Can you explain the full causal chain?
- Does fixing it consistently prevent the bug?
- Does it explain ALL observed symptoms?
- Is there nothing earlier in the chain that could be fixed?
Common Root Cause Categories
- Code Defects: logic errors, boundary conditions, race conditions, resource leaks, null/undefined handling
- Design Issues: missing error handling, inadequate validation, poor state management, coupling
- Environment: configuration errors, resource constraints, version mismatches, network issues
- Data Issues: invalid input, data corruption, schema mismatches, encoding problems
Evidence Collection Commands
# Recent changes to relevant files
git log --oneline -20 -- path/to/file
# Who changed this line
git blame path/to/file
# Changes since last working version
git diff v1.2.3..HEAD -- src/
# Search for related error handling
grep -r "catch\|error\|throw" --include="*.ts" src/Red Flags - You Haven't Found Root Cause
- "I'm not sure why, but this fix works"
- "The bug went away after I restarted"
- "I added a check to prevent this case"
- "It's probably a race condition somewhere"
These suggest symptom treatment, not root cause resolution.
Documentation Template
When root cause is found, document:
## Bug: [Description]
### Root Cause
[Clear explanation of why the bug occurred]
### Evidence
- [Evidence 1]
- [Evidence 2]
### Causal Chain
1. [Initial trigger]
2. [Intermediate cause]
3. [Root cause]
4. [Observed symptom]
### Fix
[Description of the fix and why it addresses root cause]
### Prevention
[How to prevent similar issues in the future]Integration with Other Skills
After finding root cause:
- Use testing/red-green-refactor to write a test that exposes the bug
- Use planning/verification-gates to validate the fix
- Consider collaboration/structured-review for complex fixes
© rohitg00, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in packages/core/src/methodology/packs/debugging/root-cause-analysis of rohitg00/skillkit.
Open the folder on GitHubat commit d2e5c34
Compare with similar skills
Root Cause Analysis next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Root Cause Analysis this skillrohitg00/skillkit | 1.5k | — | ~1.4k | Automated safety check: Pass | Apache-2.0 | |
| Debugging and Error Recoveryaddyosmani/agent-skills | 103k | 1 repos | ~2.6k | Automated safety check: Pass | MIT | |
| Root Cause Tracingsandgardenhq/sgai | 137 | 4 repos | ~1.4k | Automated safety check: Pass | Custom licence | |
| Codexqa Rootcause Analyzeropenqa-cn/codexqa | 152 | — | ~2.6k | Automated safety check: Pass | Apache-2.0 | |
| Debuggnomeria/usbtree | 690 | — | ~715 | Automated safety check: Pass | MIT | |
| Investigateblueberrycongee/termcanvas | 406 | — | ~562 | Automated safety check: Pass | MIT |
Similar skills
Root Cause Tracing
sandgardenhq/sgai
A skill your agent uses when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation…
Codexqa Rootcause Analyzer
openqa-cn/codexqa
Diagnoses exception root causes from stack traces, logs, call-chain dumps, and debug output using the CodexQA CLI for structured repo analysis.
Debug
gnomeria/usbtree
Systematic root-cause debugging — reproduce, isolate, fix at the source, prove the fix.
Investigate
blueberrycongee/termcanvas
Systematic debugging skill. An agent skill from blueberrycongee/termcanvas.
Production Error Hunt
different-ai/openwork
Traces an opaque production error in an OpenWork build to its cause using local server logs and Sentry, names the regressing PR and files a report.
More from rohitg00/skillkit
All 14 skills in this repoDesign First
rohitg00/skillkit
Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off…
Find Skills
rohitg00/skillkit
Discovers, searches, and installs skills from multiple AI agent skill marketplaces (400K+ skills) using the SkillKit CLI.
Handoff Protocols
rohitg00/skillkit
Manages work transitions between team members or agents by creating structured handoff documents, summarizing project status, documenting key decisions, blockers, and open questions, and generating…
Hypothesis Testing
rohitg00/skillkit
Applies the scientific method to debugging by helping users form specific, testable hypotheses, design targeted experiments, and systematically confirm or reject theories to find root causes.
Parallel Investigation
rohitg00/skillkit
Coordinates parallel investigation threads to simultaneously explore multiple hypotheses or root causes across different system areas.
Red Green Refactor
rohitg00/skillkit
Guides the red-green-refactor TDD workflow: write a failing test first, implement the minimum code to make it pass, then refactor while keeping tests green.
Related
Works with
Categories
Questions about Root Cause Analysis
What does Root Cause Analysis do?
Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Root Cause Analysis is an agent skill from rohitg00/skillkit. Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms.
When should I use Root Cause Analysis?
Root Cause Analysis fits situations like: A user reports a bug; broken behavior and needs to debug; investigate why something is not working; especially for complex.
How do I install Root Cause Analysis in Claude Code?
Run `npx skills add rohitg00/skillkit --skill root-cause-analysis -a claude-code`. Or copy the skill folder (packages/core/src/methodology/packs/debugging/root-cause-analysis in rohitg00/skillkit) into .claude/skills/root-cause-analysis in your project. Claude Code loads it when a task matches its description.
How do I install Root Cause Analysis in Codex?
Run `npx skills add rohitg00/skillkit --skill root-cause-analysis -a codex`. Or copy the skill folder (packages/core/src/methodology/packs/debugging/root-cause-analysis in rohitg00/skillkit) into .agents/skills/root-cause-analysis in your project. Codex loads it when a task matches its description.
Can I use Root Cause Analysis in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add rohitg00/skillkit --skill root-cause-analysis -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/root-cause-analysis, .gemini/skills/root-cause-analysis, .github/skills/root-cause-analysis and .opencode/skills/root-cause-analysis in your project.
What does Root Cause Analysis need to run?
Going by SKILL.md and its folder, Root Cause Analysis needs the command-line tools its instructions call (git).
Does Root Cause Analysis access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Root Cause Analysis safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Root Cause Analysis use?
Root Cause Analysis is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Root Cause Analysis use?
About 1.4k tokens (SKILL.md is roughly 5.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Root Cause Analysis?
Skills that share tags, products or a category with Root Cause Analysis: Debugging and Error Recovery (addyosmani/agent-skills, 103k stars), Root Cause Tracing (sandgardenhq/sgai, 137 stars), Codexqa Rootcause Analyzer (openqa-cn/codexqa, 152 stars) and Debug (gnomeria/usbtree, 690 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Root Cause Analysis?
rohitg00 (a GitHub user) maintains it in rohitg00/skillkit, which has 1,546 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on June 2, 2026.
Source: rohitg00/skillkit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.