root-cause-analysis · autohandai — Claude Code skill for incident analysis
Investigate outages, regressions, and recurring failures with a skill that traces evidence to underlying design flaws. Use it to draft a postmortem with a timeline and prevention tasks.
npx skills add autohandai/code-cli --skill root-cause-analysis -a claude-codeWhat root-cause-analysis does
The skill builds an incident timeline from project evidence such as Git history, configuration changes, logs, alerts, and test runs. It separates the event that triggered a failure from the underlying reason the system could not handle it, then examines the factors that allowed users to be affected. Code references help verify the proposed failure mechanism.
Its report covers impact, chronology, trigger, root cause, contributing factors, what limited the damage, and follow-up actions. Each action should identify an accountable owner, a test or check that could have caught the issue, and whether it prevents, detects, or mitigates the failure. The aim is a report engineers can act on.
The skill uses file-reading, search, repository-tree, Git history and diff, status, and command-execution tools. Findings must be tied to collected evidence, with inferences marked separately. Access to relevant project artifacts matters: without evidence to check the proposed mechanism, the report cannot establish the cause as a verified fact.
What it helps with
- Reconstruct an incident timeline from commits and logs
- Distinguish the triggering event from the underlying design flaw
- Trace a regression to the relevant code
- Write an evidence-backed incident postmortem
- Define follow-up actions that prevent or detect repeat failures
Example prompts for the agent
- Investigate the latest outage using Git history and logs, then write a postmortem with the root cause and prevention tasks.
- Trace the regression after the latest code change and support the explanation with file paths and line references.
- Review recurring failures and propose corrective actions, including a test or check for each one.
How to install root-cause-analysis
1Skills CLI (Vercel)
npx skills add autohandai/code-cli --skill root-cause-analysis -a claude-code2Manually: put the files in place
~/.claude/skills/root-cause-analysis/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/root-cause-analysis/
1Skills CLI (Vercel)
npx skills add autohandai/code-cli --skill root-cause-analysis -a codex2Manually: put the files in place
.agents/skills/root-cause-analysis/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add autohandai/code-cli --skill root-cause-analysis -a cursor2Manually: put the files in place
.cursor/skills/root-cause-analysis/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install autohandai/code-cli root-cause-analysis2Manually: put the files in place
.github/skills/root-cause-analysis/SKILL.md1Skills CLI (Vercel)
npx skills add autohandai/code-cli --skill root-cause-analysis -a gemini-cli2Platform CLI
gemini skills install https://github.com/autohandai/code-cli --path src/skills/builtin/root-cause-analysisManually: put the files in place
.devin/skills/root-cause-analysis/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add autohandai/code-cli --skill root-cause-analysis -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 root-cause-analysis
How do I install root-cause-analysis in Claude Code?
Run npx skills add autohandai/code-cli --skill root-cause-analysis -a claude-code. The installed skill file is at ~/.claude/skills/root-cause-analysis/SKILL.md.
What does root-cause-analysis do?
It examines incident evidence, traces failures to underlying design gaps, and drafts a postmortem with a timeline, contributing factors, and corrective actions.
How does a trigger differ from a root cause?
A trigger is the change or event that precedes the failure. The root cause explains why the system could not tolerate it, while contributing factors explain how the problem reached users.
Source text
SKILL.md · Apache-2.0
--- name: root-cause-analysis description: Produce a written root-cause analysis for an incident, outage, regression, or recurring failure, with a timeline, contributing factors, and prevention actions. Use for post-mortems and "why did this happen" questions. allowed-tools: read_file find_grep fff_find list_tree git_diff git_diff_range git_log git_status run_command --- # Root-cause analysis The goal is a document another engineer can act on: what happened, why it was possible, and what stops the class of failure, not just this instance. ## Gather evidence first 1. Establish the timeline from artifacts, not memory: commits (`git_log`), deploys, config changes, alerts, logs, test runs. Timestamp everything. 2. Identify the trigger (the change or event) separately from the cause (why the system could not tolerate it) and the contributing factors (what let it reach users). 3. Reproduce or at least confirm the mechanism in code with file paths and line numbers. Quote the exact lines. ## Ask "why" until the answer is a design decision Stop at a decision someone can change (a missing check, an assumed invariant, a shared resource, an unbounded wait), not at "human error". People make the same mistakes when the system makes them easy. ## Write the report Use this shape, kept short: - **Impact**: who, what, how long, blast radius. - **Timeline**: bullet list with times. - **Trigger**: the change or event. - **Root cause**: the design gap, with code references. - **Contributing factors**: detection, rollout, tests, ownership. - **What went well**: what limited the damage. - **Actions**: each with an owner-shaped verb, a test or check that would have caught it, and whether it prevents, detects, or mitigates. Prefer changes to the system over reminders to people. ## Verify before delivering Every claim in the report must trace to evidence you collected. If something is inferred, label it as such. Offer to open the follow-up tasks.
© autohandai · Apache-2.0 · autohandai/code-cli
Similar skills
All skills for DevOps and infrastructure →root-cause-analysis by other authors comes first.
