Agent skill

Root Cause Tracing

Systematically trace bugs backward through call stack to find original trigger.

MITAuto-check passedDevelopment

Install Root Cause Tracing

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a claude-code

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

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing --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/secondsky/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .claude/skills/root-cause-tracing && 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/

Paste into Claude Code

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .claude/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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

$skill-installer install https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing

Type 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.

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .agents/skills/root-cause-tracing && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .agents/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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.

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .cursor/skills/root-cause-tracing && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .cursor/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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

$ gemini skills install https://github.com/secondsky/claude-skills.git --path plugins/root-cause-tracing/skills/root-cause-tracing

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .gemini/skills/root-cause-tracing && rm -rf skills-src

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

Paste into Gemini CLI

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .gemini/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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.

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing

Installs 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).

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .github/skills/root-cause-tracing && rm -rf skills-src

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

Paste into GitHub Copilot

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .github/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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.

skills CLI

$ npx skills add secondsky/claude-skills --skill root-cause-tracing -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills root-cause-tracing --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/plugins/root-cause-tracing/skills/root-cause-tracing .opencode/skills/root-cause-tracing && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "root-cause-tracing" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing into .opencode/skills/root-cause-tracing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "root-cause-tracing", 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-tracing
GitHub stars: 227
Used in: 1 other repo
Token cost: ~1k tokens
SKILL.md length: 398 words
Files: 1
Skills in repo: 169
Repo updated: Sep 28, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Systematically trace bugs backward through call stack to find original trigger.

Works in 5 steps: Observe the Symptom → Find Immediate Cause → Ask: What Called This? → …
Errors occur deep in execution and you need to trace back to find the original trigger
SKILL.md covers Overview, When to Use, The Tracing Process and Adding Stack Traces, plus 5 more sections
Calls bun and git

What it does

Root Cause Tracing is an agent skill from secondsky/claude-skills. Systematically trace bugs backward through call stack to find original trigger. Use when errors occur deep in execution and you need to trace back to find the original trigger.

Its SKILL.md is about 1k 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: Production-ready skills for Claude Code CLI - Cloudflare, React, Tailwind v4, and AI integrations. The licence is MIT.

When your agent uses it

Errors occur deep in execution and you need to trace back to find the original trigger
Tasks that involve Root cause analysis
Tasks that involve Debugging

Example prompts

“/root-cause-tracing”

Workflow steps

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

Observe the Symptom
Find Immediate Cause
Ask: What Called This?
Keep Tracing Up
Find Original Trigger

What it can do on your machine

Read from SKILL.md and the folder at commit 8837836. 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:
- bun
- 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 Tracing loads about 1k tokens when it runs. Until then it costs about 49 tokens; SKILL.md has 398 words of instructions outside code blocks.

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

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 secondsky/claude-skills at commit 8837836, republished under its MIT licence (© secondsky). 398 words, ~1,025 tokens.

Download SKILL.mdSave it as .claude/skills/root-cause-tracing/SKILL.md (or your agent's skills folder).

name: root-cause-tracing
description: Systematically trace bugs backward through call stack to find original trigger. Use when errors occur deep in execution and you need to trace back to find the original trigger.
metadata.version: 1.1.0
license: MIT

Root Cause Tracing

Overview

Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.

Core principle: Trace backward through the call chain until you find the original trigger, then fix at the source.

When to Use

Use when:

Error happens deep in execution (not at entry point)
Stack trace shows long call chain
Unclear where invalid data originated
Need to find which test/code triggers the problem

The Tracing Process

1. Observe the Symptom

Error: git init failed in ~/project/packages/core

2. Find Immediate Cause

What code directly causes this?

typescript

await execFileAsync('git', ['init'], { cwd: projectDir });

3. Ask: What Called This?

typescript

WorktreeManager.createSessionWorktree(projectDir, sessionId)
  → called by Session.initializeWorkspace()
  → called by Session.create()
  → called by test at Project.create()

4. Keep Tracing Up

What value was passed?

projectDir = '' (empty string!)
Empty string as cwd resolves to process.cwd()
That's the source code directory!

5. Find Original Trigger

Where did empty string come from?

typescript

const context = setupCoreTest(); // Returns { tempDir: '' }
Project.create('name', context.tempDir); // Accessed before beforeEach!

Adding Stack Traces

When you can't trace manually, add instrumentation:

typescript

// Before the problematic operation
async function gitInit(directory: string) {
  const stack = new Error().stack;
  console.error('DEBUG git init:', {
    directory,
    cwd: process.cwd(),
    nodeEnv: process.env.NODE_ENV,
    stack,
  });

  await execFileAsync('git', ['init'], { cwd: directory });
}

Critical: Use console.error() in tests (not logger - may not show)

Run and capture:

bash

bun test 2>&1 | grep 'DEBUG git init'

Analyze stack traces:

Look for test file names
Find the line number triggering the call
Identify the pattern (same test? same parameter?)

Finding Which Test Causes Pollution

If something appears during tests but you don't know which test:

Use the bisection script to run tests one-by-one:

bash

# Example: find which test creates .git in wrong place
bun test --run --bail 2>&1 | tee test-output.log

Runs tests one-by-one, stops at first polluter.

Show full SKILL.md (175 more words)Show less

Real Example: Empty projectDir

Symptom: .git created in packages/core/ (source code)

Trace chain:

git init runs in process.cwd() ← empty cwd parameter
WorktreeManager called with empty projectDir
Session.create() passed empty string
Test accessed context.tempDir before beforeEach
setupCoreTest() returns { tempDir: '' } initially

Root cause: Top-level variable initialization accessing empty value

Fix: Made tempDir a getter that throws if accessed before beforeEach

Also added defense-in-depth:

Layer 1: Project.create() validates directory
Layer 2: WorkspaceManager validates not empty
Layer 3: NODE_ENV guard refuses git init outside tmpdir
Layer 4: Stack trace logging before git init

Key Principle

NEVER fix just where the error appears. Trace back to find the original trigger.

Stack Trace Tips

In tests: Use console.error() not logger - logger may be suppressed Before operation: Log before the dangerous operation, not after it fails Include context: Directory, cwd, environment variables, timestamps Capture stack: new Error().stack shows complete call chain

Real-World Impact

From debugging session:

Found root cause through 5-level trace
Fixed at source (getter validation)
Added 4 layers of defense
1847 tests passed, zero pollution

Files

Just SKILL.md in plugins/root-cause-tracing/skills/root-cause-tracing of secondsky/claude-skills.

Open the folder on GitHubat commit 8837836

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in secondsky/claude-skills, which our catalogue first saw on October 7, 2026.

majiayu000/claude-skill-registryskills/analysis/root-cause-tracing-secondsky-claude-skills-2

Compare with similar skills

Root Cause Tracing 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 Tracing compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Root Cause Tracing this skillsecondsky/claude-skills	227	1 repos	~1k	Automated safety check: Pass	MIT	9 days ago
Debugging and Error Recoveryaddyosmani/agent-skills	102k	1 repos	~2.6k	Automated safety check: Pass	MIT	4 days ago
Codexqa Rootcause Analyzeropenqa-cn/codexqa	152	—	~2.6k	Automated safety check: Pass	Apache-2.0	5 days ago
Root Cause Tracingsandgardenhq/sgai	137	3 repos	~1.4k	Automated safety check: Pass	Custom licence	17 days ago
Debuggnomeria/usbtree	688	—	~715	Automated safety check: Pass	MIT	1 mo ago
Root Cause Analysisrohitg00/skillkit	1.5k	—	~1.4k	Automated safety check: Pass	Apache-2.0	4 mo ago

Similar skills

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.
102k GitHub starsUsed in 1 repo~2.6k tokens
DevelopmentAuto-check passed
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.
152 GitHub stars~2.6k tokensUpdated 5 days ago
DevelopmentAuto-check passed
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…
137 GitHub starsUsed in 3 repos~1.4k tokens
DevelopmentAuto-check passed
Debug
gnomeria/usbtree
Systematic root-cause debugging — reproduce, isolate, fix at the source, prove the fix.
688 GitHub stars~715 tokensUpdated 1 mo ago
DevelopmentAuto-check passed
Root Cause Analysis
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.
1.5k GitHub stars~1.4k tokensUpdated 4 mo ago
DevelopmentAuto-check passed
Investigate
blueberrycongee/termcanvas
Systematic debugging skill. An agent skill from blueberrycongee/termcanvas.
406 GitHub stars~562 tokensUpdated 4 mo ago
DevelopmentAuto-check passed

More from secondsky/claude-skills

All 169 skills in this repo

Tanstack AI
secondsky/claude-skills
TanStack AI (alpha) provider-agnostic type-safe chat with streaming for OpenAI, Anthropic, Gemini, Ollama.
227 GitHub starsUsed in 1 repo~3.6k tokens
Auto-check: notes
Auto Animate
secondsky/claude-skills
AutoAnimate (@formkit/auto-animate) zero-config animations for React.
227 GitHub stars~2.9k tokensUpdated 9 days ago
Auto-check passed
Base UI React
secondsky/claude-skills
MUI Base UI unstyled React components with Floating UI. An agent skill from secondsky/claude-skills.
227 GitHub stars~1.9k tokensUpdated 9 days ago
Auto-check passed
Cloudflare Images
secondsky/claude-skills
This skill should be used when the user asks to "upload images to Cloudflare", "implement direct creator upload", "configure image transformations", "optimize WebP/AVIF", "create image variants"…
227 GitHub stars~3.6k tokensUpdated 9 days ago
Auto-check: notes
Cloudflare Nextjs
secondsky/claude-skills
Deploy Next.js to Cloudflare Workers via the OpenNext adapter (@opennextjs/cloudflare).
227 GitHub stars~5.3k tokensUpdated 9 days ago
Auto-check: notes
Cloudflare Sandbox
secondsky/claude-skills
Cloudflare Sandboxes SDK for secure code execution in Linux containers at edge.
227 GitHub stars~4.5k tokensUpdated 9 days ago
Auto-check passed

Works with

Questions about Root Cause Tracing

What does Root Cause Tracing do?

Systematically trace bugs backward through call stack to find original trigger. Root Cause Tracing is an agent skill from secondsky/claude-skills. Systematically trace bugs backward through call stack to find original trigger.

When should I use Root Cause Tracing?

Root Cause Tracing fits situations like: errors occur deep in execution and you need to trace back to find the original trigger; tasks that involve Root cause analysis; tasks that involve Debugging.

How do I install Root Cause Tracing in Claude Code?

Run `npx skills add secondsky/claude-skills --skill root-cause-tracing -a claude-code`. Or copy the skill folder (plugins/root-cause-tracing/skills/root-cause-tracing in secondsky/claude-skills) into .claude/skills/root-cause-tracing in your project. Claude Code loads it when a task matches its description.

How do I install Root Cause Tracing in Codex?

Run `npx skills add secondsky/claude-skills --skill root-cause-tracing -a codex`. Or copy the skill folder (plugins/root-cause-tracing/skills/root-cause-tracing in secondsky/claude-skills) into .agents/skills/root-cause-tracing in your project. Codex loads it when a task matches its description.

Can I use Root Cause Tracing 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 secondsky/claude-skills --skill root-cause-tracing -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-tracing, .gemini/skills/root-cause-tracing, .github/skills/root-cause-tracing and .opencode/skills/root-cause-tracing in your project.

What does Root Cause Tracing need to run?

Going by SKILL.md and its folder, Root Cause Tracing needs the command-line tools its instructions call (bun and git).

Does Root Cause Tracing 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 Tracing 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 Tracing use?

Root Cause Tracing is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Root Cause Tracing use?

About 1k tokens (SKILL.md is roughly 4.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 Tracing?

Skills that share tags, products or a category with Root Cause Tracing: Debugging and Error Recovery (addyosmani/agent-skills, 102k stars), Codexqa Rootcause Analyzer (openqa-cn/codexqa, 152 stars), Root Cause Tracing (sandgardenhq/sgai, 137 stars) and Debug (gnomeria/usbtree, 688 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Root Cause Tracing?

secondsky (a GitHub user) maintains it in secondsky/claude-skills, which has 227 GitHub stars. The repository holds 169 skills in this directory. The repository was last updated on September 28, 2026.

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

Install Root Cause Tracing

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Root Cause Tracing

Overview

When to Use

The Tracing Process

1. Observe the Symptom

2. Find Immediate Cause

3. Ask: What Called This?

4. Keep Tracing Up

5. Find Original Trigger

Adding Stack Traces

Finding Which Test Causes Pollution

Real Example: Empty projectDir

Key Principle

Stack Trace Tips

Real-World Impact

Files

Used in 1 other repository

Compare with similar skills

Similar skills

More from secondsky/claude-skills

Related

Questions about Root Cause Tracing