diagnosing-root-causes — Claude Code skill: trace failures
The diagnosing-root-causes skill traces bugs, regressions, and CI/CD failures from supplied evidence, then produces a reviewed root-cause report. Use it when a problem report needs investigation rather than guesswork.
no license 122 installs ★ 3 updated 2026-10-25
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a claude-codeWhat diagnosing-root-causes does
Give the skill an issue description and materials such as logs, repository paths, CI output, or a commit range. It classifies the report, asks for clarification when needed, then routes evidence gathering, causal analysis, and report review to three subagents. The final conclusions are tied to supporting evidence.
The workflow follows a finite state machine. Investigation is read-only by default, and the skill never performs Tier C actions, even with approval; approval can produce a handoff for a person instead. That boundary matters if you expect the agent to change code or run a risky operation. When the environment has no subagent tool, the phases run in one context, so the report review is not independent.
Provide the problem and its supporting materials to start. Reproduction steps, environment details, and the issue source can add context. Reports end with ready, blocked, needs-validation, or escalated; early stops use needs-input or error.
What it helps with
- trace an application crash from logs
- investigate a regression after a code change
- identify why a CI/CD pipeline fails
- check whether a bug report has enough evidence
- prepare a reviewable root-cause report
Example prompts for the agent
- Investigate the application failure using
logs/build-42.txtand separate confirmed findings from hypotheses. - Find why the CI/CD pipeline failed after the dependency update using the supplied logs and commit range.
- Review this bug report and ask for the missing details needed to investigate it.
How to install diagnosing-root-causes
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a claude-code2Manually: put the files in place
~/.claude/skills/diagnosing-root-causes/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagnosing-root-causes/
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a codex2Manually: put the files in place
.agents/skills/diagnosing-root-causes/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a cursor2Manually: put the files in place
.cursor/skills/diagnosing-root-causes/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install b-mendoza/agent-skills skills/diagnosing-root-causes2Manually: put the files in place
.github/skills/diagnosing-root-causes/SKILL.md1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a gemini-cli2Platform CLI
gemini skills install https://github.com/b-mendoza/agent-skills --path skills/diagnosing-root-causesManually: put the files in place
.devin/skills/diagnosing-root-causes/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -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 diagnosing-root-causes
How do I install diagnosing-root-causes in Claude Code?
Run npx skills add b-mendoza/agent-skills --skill diagnosing-root-causes -a claude-code. The skill file is placed at ~/.claude/skills/diagnosing-root-causes/SKILL.md.
What does diagnosing-root-causes do?
It gathers evidence about a reported issue, delegates causal analysis, and checks the resulting report. It covers bugs, regressions, and CI/CD failures.
Can the skill apply a fix itself?
No. It stays read-only for its investigation and does not perform Tier C actions, even after approval. An approved action at that tier is packaged for human-supervised execution.