New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Root Cause Debugging

by jsmastery-pro in jsmastery-pro/skills

Runs a reproduce, localize, hypothesize, test, fix and verify loop to find a bug's root cause, applies the minimal fix and hands off a regression test.

MITAuto-check: notesDevelopment

Install Root Cause Debugging

skills CLI
$ npx skills add jsmastery-pro/skills --skill debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jsmastery-pro/skills debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jsmastery-pro/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/debug .claude/skills/debug && rm -rf skills-src

Use ~/.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/

Facts

Skill name
debug
GitHub stars
1.4k
Token cost
~1.8k tokens
SKILL.md length
1,020 words
Files
2
Skills in repo
8
Repo updated
First seen
Licence
MIT

At a glance

Runs a reproduce, localize, hypothesize, test, fix and verify loop to find a bug's root cause, applies the minimal fix and hands off a regression test.

  • Works in 7 steps: Capture the symptom → Reproduce reliably → Localize → …
  • A test fails for a reason nobody understands yet
  • SKILL.md covers Output style (plain words, no…, What this skill does, Asks vs acts and Artifact ownership, plus 2 more sections
  • Calls git

What it does

Invoked with `/debug`, this skill treats a bug as a case to prove. The agent reproduces it on demand, narrows it to the smallest failing surface and changes one thing at a time, testing a single hypothesis at a time and confirming or rejecting each with evidence before touching the code. It resists patching the visible symptom, such as a null or a crash, before understanding why it appears.

It acts rather than asks, questioning you only when it cannot reproduce the bug, and then for exact steps, inputs, environment and observed versus expected behavior. The result is the smallest code fix for the proven cause, plus either a recommendation to run `/test` for the regression test or a failing-then-passing test written inline. It adds no features and refactors nothing unrelated, and if the bug reflects a flawed decision it points to `/architect`. Output is written in plain, simple language without dashes.

When your agent uses it

  • A test fails for a reason nobody understands yet
  • A verification run found a failure that needs a root cause
  • Behavior is wrong and you want a minimal, proven fix

Example prompts

  • “/debug the checkout test that fails only on CI.”
  • “The invoice total is off by one cent for some orders; find the root cause and fix it.”
  • “Find out why the login redirect loops and add a regression test.”

Requirements

  • Pre-approved tools (allowed-tools): Bash, Read, Grep, Glob, Write, Edit, Agent

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Capture the symptom
  2. Reproduce reliably
  3. Localize
  4. Hypothesize (one at a time)
  5. Test the hypothesis
  6. Fix at the root
  7. Verify and protect

What it can do on your machine

Read from SKILL.md and the folder at commit 43b69e4. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash
    • Read
    • Grep
    • Glob
    • Write
    • Edit
    • Agent

    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 Debugging loads about 1.8k tokens when it runs. Until then it costs about 77 tokens; SKILL.md has 1,020 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~77
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

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: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent

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 jsmastery-pro/skills at commit 43b69e4, republished under its MIT licence (© jsmastery-pro). 1,020 words, ~1,778 tokens.

Download SKILL.mdSave it as .claude/skills/debug/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
debug
description
Run /debug to find and fix a bug's root cause: a test failing for an unclear reason, /check verify finding a failure, or behavior being wrong. Runs a reproduce, localize, hypothesize, test, fix, verify loop, makes the minimal fix, and hands a regression test to /test. No features, no extra refactors.
allowed-tools
Bash, Read, Grep, Glob, Write, Edit, Agent

Output style (plain words, no dashes, no hyphens)

<!-- OUTPUT-STYLE:START -->

Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as you, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write read only, not read-only. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.

<!-- OUTPUT-STYLE:END -->

What this skill does

Your role: the investigator who trusts evidence over intuition. Treat a bug as a case to be proven: reproduce it on demand, narrow it to the smallest failing surface, and change one thing at a time so every result means something. Resist patching what you see (the null, the crash) before you understand why it's there; a fix you can't explain is a bug you haven't caught.

A structured root cause investigation, not a guess and check. Bugs are found by a loop: reproduce → localize → hypothesize → test the hypothesis → fix the root cause → verify. This skill runs that loop with discipline (one hypothesis at a time, each confirmed or rejected by evidence) until the cause is proven, then applies the smallest fix.

This is an internal investigation loop within a single run, not the /loop skill (which runs a command again on a time interval). Reach for /loop only when you need to watch something over time, e.g. poll a flaky test across many runs.

Asks vs acts

Acts. It reproduces, investigates, and fixes. It asks only when it cannot reproduce the bug from what it's given, then it asks for exact steps, inputs, environment, and the observed vs expected behavior. It does not ask permission to investigate.

Artifact ownership

Writes the minimal code fix for the root cause. Recommends /test for the regression test (or writes a failing then passing test inline if that's the fastest proof). Does not add features, refactor unrelated code, or rewrite the spec. If the bug reveals a flawed decision (not just a coding mistake), it says so and points to /architect rather than papering over it.

Portability (any OS, any agent)

Written for any Agent Skills client on macOS, Linux, or Windows. Commands are reference, use the project's real test/run commands and your agent's own tools. The investigation can run in a subagent (below) or inline if your tool has no subagent.

Execution

Step 0: Capture the symptom

Pin down precisely, before touching code:

  • Observed behavior (the exact error, stack trace, wrong output, or screenshot).
  • Expected behavior.
  • Repro: the steps, inputs, and environment that trigger it.

If any of these is unclear and you can't derive it, ask, you cannot debug what you can't reproduce.

Step 1: Reproduce reliably

Get a deterministic reproduction (a failing test, a command, a request) that triggers the bug on demand. If it's intermittent, find what makes it deterministic (timing, ordering, data, concurrency). A bug you can't reproduce on command, you can't prove you've fixed. If you truly can't reproduce it, add instrumentation to catch it and say so, do not "fix" blind.

Step 2: Localize

Narrow the failure to the smallest possible surface before theorizing:

  • Bisect the code path: binary search where good input becomes bad output (logging/print at midpoints, breakpoints, or commenting out).
  • Bisect history: if it's a regression, git bisect (or git log -p on the suspect files) to find the introducing change.
  • Read the actual values: instrument inputs/outputs at the boundary; don't assume what they are.
Show full SKILL.md (398 more words)Show less
Step 3: Hypothesize (one at a time)

State a single, specific, falsifiable hypothesis for the root cause, e.g. "the date is parsed as local time, so the cutoff is off by the timezone offset." Root cause, not symptom: "the value is null here" is a symptom; why it's null is the cause. Resist shotgun changing several things at once.

Step 4: Test the hypothesis

Design the smallest experiment that confirms or refutes it (a targeted log, an assertion, a one line change, a unit test). Run it.

  • Refuted → discard it, return to Step 2/3 with what you learned. Do not keep a change that didn't help.
  • Confirmed → you've found the root cause. Proceed.

Loop Steps 3 to 4 until a hypothesis is confirmed by evidence. Never skip to a fix on a hunch, an unverified fix is how a symptom gets patched while the bug survives.

Step 5: Fix at the root

Make the minimal, targeted change that addresses the proven cause. Don't fix the symptom (clamping the null), fix the cause (why it's null). Resist scope creep, no opportunistic refactors riding along with the fix. Follow the project's conventions (AGENTS.md, neighbouring code).

Step 6: Verify and protect
  • Run the Step 1 reproduction again, confirm it now passes.
  • Run the surrounding test suite, confirm no regression.
  • Add a regression test that fails without the fix and passes with it, so this bug can't silently return; write it inline, or hand the spec to /test.
  • Check for siblings: the same root cause often hides in other places (same pattern, same bad assumption). Grep for them and note or fix them.
Optional: run it in a subagent

For a hunt that is not trivial, spawn an investigation subagent so the iterative tool use doesn't fill the main context:

  • model: set explicitly to a strong model, do not inherit the session model (Claude Code: sonnet)
  • description: "Debug: <symptom>"
  • Tools: Read, Bash, Grep, Glob, Edit, Write
  • prompt: this loop + the captured symptom + reproduction + the relevant AGENTS.md (inlined). Require it to report the root cause with evidence, not just "fixed it."
Report

Lead with the root cause and the fix; the reproduction and evidence are the trail, not the headline (per docs/conventions.md). Template:

## /debug complete · <the bug, one line>

**Root cause: <the proven cause>. Fixed by <the minimal change, files touched>.**
Next: /test <feature>   (lock in the regression test, added inline or handed over)
Heads up: <same cause also at <where>, fixed too · or a design flaw → /architect <what>>   (omit if none)

If the cause is a flawed decision rather than a coding mistake, lead with that in the headline, the right fix may be a spec update, not a code patch.

© jsmastery-pro, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/debug of jsmastery-pro/skills.

  • SKILL.md
  • agents/openai.yaml

Open the folder on GitHubat commit 43b69e4

Compare with similar skills

Root Cause Debugging 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.

Root Cause Debugging compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Root Cause Debugging this skilljsmastery-pro/skills1.4k—~1.8kAutomated safety check: NotesMIT
Superpowers Systematic Debuggingchristopherarter/superpowers-reasonix102—~2kAutomated safety check: PassMIT
Minimal Code Fixcobusgreyling/loop-engineering11k1 repos~345Automated safety check: NotesMIT
Failure Diagnosis LoopTotoro-jam/battle-tested-patterns343—~319Automated safety check: PassMIT
Hypothesis-Driven DebuggingLichAmnesia/lich-skills234—~2.5kAutomated safety check: PassMIT
Systematic Debuggingcbrock84/headcount2k—~657Automated safety check: PassMIT

Similar skills

  • Superpowers Systematic Debugging

    christopherarter/superpowers-reasonix

    Any bug, failing or flaky test, or surprise behavior?. An agent skill from christopherarter/superpowers-reasonix.

    102 GitHub stars~2k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

  • Minimal Code Fix

    cobusgreyling/loop-engineering

    Makes the smallest code change that fixes one well-scoped problem, such as a CI failure, review comment or typo, without refactoring anything unrelated.

    11k GitHub starsUsed in 1 repo~345 tokens
    DevelopmentAuto-check: notes

  • Failure Diagnosis Loop

    Totoro-jam/battle-tested-patterns

    Walks the agent through a fixed loop for failing tests and build errors: reproduce, isolate, hypothesize, instrument, fix, verify, then add a regression test.

    343 GitHub stars~319 tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

  • Hypothesis-Driven Debugging

    LichAmnesia/lich-skills

    Replaces trial-and-error fixing with an observe, hypothesize, experiment and conclude loop kept in DEBUG.md, where no fix is allowed before evidence supports a cause.

    234 GitHub stars~2.5k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed

  • Systematic Debugging

    cbrock84/headcount

    Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix.

    2k GitHub stars~657 tokensUpdated 19 days ago
    DevelopmentAuto-check passed

  • Test Guided Bug Detector

    ArabelaTso/Skills-4-SE

    Analyze failing tests to detect functional bugs in code. An agent skill from ArabelaTso/Skills-4-SE.

    253 GitHub stars~2.8k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

More from jsmastery-pro/skills

All 8 skills in this repo

  • Pre-Merge Check

    jsmastery-pro/skills

    A gate before merge: verify runs the real app against the spec, and review has a different model do a senior code review, without editing code.

    1.4k GitHub stars~1.1k tokensUpdated 1 mo ago
    Auto-check: notes

  • Develop Feature Builder

    jsmastery-pro/skills

    Builds a feature, page, component, API or data layer from an approved spec and AGENTS.md, and sends you back to /architect when a key decision is missing.

    1.4k GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check: notes

  • Change Documentation Writer

    jsmastery-pro/skills

    Writes PR descriptions, changelog entries, release notes and postmortems from the actual commits and diff, and saves each one in the right place.

    1.4k GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check: notes

  • Sync Project Knowledge

    jsmastery-pro/skills

    Runs as the last step after a completed change to keep AGENTS.md files, the project scope and linked spec status lines current, using only small surgical edits.

    1.4k GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check: notes

  • Project Context Auditor

    jsmastery-pro/skills

    Bootstraps a project's tool-agnostic AGENTS.md files for a greenfield project, an undocumented codebase or one area, adding only what is missing and never overwriting curated content.

    1.4k GitHub stars~3.2k tokensUpdated 1 mo ago
    Auto-check: notes

  • Living Product Scope Planner

    jsmastery-pro/skills

    Turns a product idea into a coarse, ordered scope kept in docs/scope, then keeps it current: plan a product, plan the next slice, enroll one feature or reconcile after shipping.

    1.4k GitHub stars~2.8k tokensUpdated 1 mo ago
    Auto-check: notes

Categories

Questions about Root Cause Debugging

What does Root Cause Debugging do?

Runs a reproduce, localize, hypothesize, test, fix and verify loop to find a bug's root cause, applies the minimal fix and hands off a regression test. Invoked with `/debug`, this skill treats a bug as a case to prove. The agent reproduces it on demand, narrows it to the smallest failing surface and changes one thing at a time, testing a single hypothesis at a time and confirming or rejecting each with evidence before touching the code.

When should I use Root Cause Debugging?

Root Cause Debugging fits situations like: A test fails for a reason nobody understands yet; A verification run found a failure that needs a root cause; behavior is wrong and you want a minimal, proven fix.

How do I install Root Cause Debugging in Claude Code?

Run `npx skills add jsmastery-pro/skills --skill debug -a claude-code`. Or copy the skill folder (skills/debug in jsmastery-pro/skills) into .claude/skills/debug in your project. Claude Code loads it when a task matches its description.

How do I install Root Cause Debugging in Codex?

Run `npx skills add jsmastery-pro/skills --skill debug -a codex`. Or copy the skill folder (skills/debug in jsmastery-pro/skills) into .agents/skills/debug in your project. Codex loads it when a task matches its description.

Can I use Root Cause Debugging 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 jsmastery-pro/skills --skill debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debug, .gemini/skills/debug, .github/skills/debug and .opencode/skills/debug in your project.

What does Root Cause Debugging need to run?

Going by SKILL.md and its folder, Root Cause Debugging needs the command-line tools its instructions call (git). Its frontmatter pre-approves these tools: Bash, Read, Grep, Glob, Write, Edit, Agent.

Does Root Cause Debugging 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 Debugging safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Root Cause Debugging use?

Root Cause Debugging is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Root Cause Debugging use?

About 1.8k tokens (SKILL.md is roughly 7.1k 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 Debugging?

Skills that share tags, products or a category with Root Cause Debugging: Superpowers Systematic Debugging (christopherarter/superpowers-reasonix, 102 stars), Minimal Code Fix (cobusgreyling/loop-engineering, 11k stars), Failure Diagnosis Loop (Totoro-jam/battle-tested-patterns, 343 stars) and Hypothesis-Driven Debugging (LichAmnesia/lich-skills, 234 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Root Cause Debugging?

jsmastery-pro (a GitHub organization) maintains it in jsmastery-pro/skills, which has 1,429 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on August 9, 2026.

Source: jsmastery-pro/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.