New: 98,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

Debug

by softspark in softspark/ai-toolkit

Systematic debugging via logs, health checks, hypothesis-driven investigation.

Apache-2.0Auto-check: notesDevelopment

Install Debug

skills CLI
$ npx skills add softspark/ai-toolkit --skill debug -a claude-code

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

GitHub CLI
$ gh skill install softspark/ai-toolkit 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/softspark/ai-toolkit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/app/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
179
Token cost
~2.1k tokens
SKILL.md length
810 words
Files
2 (incl. scripts)
Skills in repo
112
Repo updated
First seen
Licence
Apache-2.0

At a glance

Systematic debugging via logs, health checks, hypothesis-driven investigation.

  • Works in 8 steps: Root Cause Investigation → Pattern Analysis → Hypothesis & Testing → …
  • Tasks that involve Debugging
  • SKILL.md covers Project context, Automated Error Parsing, Methodology — The Iron Law and Debugging Workflow, plus 8 more sections
  • Runs Python scripts from its folder; calls docker, curl and python3

What it does

Debug is an agent skill from softspark/ai-toolkit. Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/error-parser.py`).

It sits in Development, covering Debugging and Root cause analysis. The repository describes itself as: Professional-grade AI coding toolkit: 94 skills, 44 agents, multi-platform (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Antigravity, Codex CLI… The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Debugging
  • Tasks that involve Root cause analysis

Example prompts

  • “/debug”

Requirements

  • Python 3
  • Node.js
  • Docker
  • Pre-approved tools (allowed-tools): Bash, Read, Grep

Workflow steps

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

  1. Root Cause Investigation
  2. Pattern Analysis
  3. Hypothesis & Testing
  4. Implementation
  5. Check Logs
  6. Check Service Health
  7. Interactive Debug
  8. Database Checks

What it can do on your machine

Read from SKILL.md and the folder at commit d64db2b. 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

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • docker
    • curl
    • python3
    • redis-cli
    • python
    • java
    • node
    • php
    • psql
    • mysql
    • mongosh
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use docker, curl and 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

Debug loads about 2.1k tokens when it runs. Until then it costs about 42 tokens; SKILL.md has 810 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~42
When it runs · the whole SKILL.md, loaded when a task matches
~2.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: 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

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); the scripts in this folder are not scanned.

SKILL.md

The full file from softspark/ai-toolkit at commit d64db2b, republished under its Apache-2.0 licence (© softspark). 810 words, ~2,092 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
Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.
allowed-tools
Bash, Read, Grep
user-invocable
true
effort
xhigh
argument-hint
[symptom]
agent
debugger
context
fork

Debug Helper

$ARGUMENTS

Systematic debugging for application issues.

Project context

  • Recent logs: !docker compose logs --tail 20 2>/dev/null || tail -20 logs/*.log 2>/dev/null || echo "no-logs-found"

Automated Error Parsing

Pipe error output through the error parser for structured diagnosis:

bash
# Pipe from failing command
your_command 2>&1 | python3 ${CLAUDE_SKILL_DIR}/scripts/error-parser.py

# Or from a log file
cat /var/log/app/error.log | python3 ${CLAUDE_SKILL_DIR}/scripts/error-parser.py

The script outputs JSON with:

  • language: detected language (python/node/go/php)
  • error_type: extracted error class (e.g., ModuleNotFoundError)
  • message: the error message text
  • category: classification (import, reference, type, connection, timeout, memory, permission, syntax)
  • stack_frames: parsed file/line/function from the stack trace
  • files_to_check: unique files from the trace, ordered by relevance
  • common_causes: likely root causes for this error category

Use the parsed output to focus investigation on the right files and hypotheses.

Methodology — The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Quick patches mask underlying issues. Complete each phase before proceeding to the next.

Phase 1 — Root Cause Investigation

Read error messages and stack traces completely. Reproduce reliably (or gather more data — don't guess). Check recent changes (git diff, new deps, config). For multi-component systems: log boundary in/out at each layer, identify WHERE it breaks before WHY.

Phase 2 — Pattern Analysis

Find similar working code in the same codebase. Compare against references completely, not skimming. List every difference, however small.

Phase 3 — Hypothesis & Testing

Form a single hypothesis ("X is the root cause because Y"). Test minimally — smallest possible change, one variable at a time. Verify before continuing — if it didn't work, form a NEW hypothesis. Don't stack fixes on top of fixes.

Phase 4 — Implementation

Write a failing test case FIRST (use /tdd). Implement single fix at root cause. No "while I'm here" improvements.

"5 Whys" — depth gate

Ask "Why?" at least 5 times to find the real issue. Stop at the first plausible answer = symptom fixing. Example: crash → null pointer → user object null → API 404 → invalid user ID → frontend allowed negative IDs (root cause).

Architecture escalation (3+ failed fixes)

If three hypotheses failed and each fix reveals new shared state in different places, the architecture is wrong, not your hypothesis. STOP. Discuss with user before more attempts.

Debugging Workflow

1. Check Logs
bash
# Application logs (auto-detect environment)
# Docker:
docker compose logs --tail 100 {service} 2>&1 | grep -i error

# Bare metal / systemd:
journalctl -u {service} --since "1 hour ago" | grep -i error

# Log files:
tail -100 logs/app.log | grep -i error
2. Check Service Health
bash
# Docker environment
docker compose ps

# Process check
ps aux | grep -E "(node|python|java|php)" | grep -v grep

# HTTP health endpoints
curl -sf http://localhost:{port}/health
3. Interactive Debug
bash
# Python
python3 -c "import module; print(module.function('test'))"

# Node.js
node -e "const m = require('./module'); console.log(m.fn('test'))"

# PHP
php -r "require 'vendor/autoload.php'; echo MyClass::method('test');"
4. Database Checks
bash
# PostgreSQL
psql -U postgres -c "SELECT version();"

# MySQL
mysql -e "SELECT VERSION();"

# Redis
redis-cli ping && redis-cli info memory

# MongoDB
mongosh --eval "db.runCommand({ping:1})"

Common Debug Scenarios

API Returns 500
bash
# Check server logs for stack traces
grep -A5 "Traceback\|Error\|Exception" logs/app.log
Slow Performance
bash
# Resource usage
top -bn1 | head -20     # CPU/memory
iostat -x 1 3            # Disk I/O
ss -tlnp                 # Open connections
Connection Issues
bash
# Test connectivity
curl -I http://localhost:{port}
nc -zv {host} {port}

Parallel Hypothesis Debugging (Agent Teams)

For complex bugs (open >1h, unclear root cause), spawn teammates to investigate competing hypotheses:

Create an agent team to debug this issue:
- Teammate 1 (debugger): "Investigate if [bug] is caused by [hypothesis A: database issue].
  Check logs, connection pools, timeouts, query performance."
  Use Opus.
- Teammate 2 (debugger): "Investigate if [bug] is caused by [hypothesis B: race condition].
  Look for async issues, locking, concurrency, shared state."
  Use Opus.
- Teammate 3 (debugger): "Investigate if [bug] is caused by [hypothesis C: configuration drift].
  Compare env vars, config files, recent changes, dependency versions."
  Use Opus.
Have them talk to each other to challenge each other's theories.
Report consensus when done.

Common Rationalizations

ExcuseWhy It's Wrong
"It works on my machine"Environment differences are the #1 cause of production bugs — reproduce in prod-like env
"It must be a library bug"95% of the time it's your code — exhaust local hypotheses first
"I'll just add more logging and wait"Passive debugging wastes hours — form a hypothesis and test it actively
"The error message says X, so it must be X"Error messages often describe symptoms, not root causes — trace the full chain
"It only happens sometimes, probably a fluke"Intermittent bugs are race conditions or state leaks — they get worse, not better
Show full SKILL.md (331 more words)Show less

Debug Checklist

  • Identified error/symptom
  • Checked relevant logs
  • Verified service health
  • Reproduced issue
  • Formed hypothesis
  • Tested fix

Rules

  • MUST form a testable hypothesis before changing code
  • NEVER apply fixes without first reproducing the symptom
  • CRITICAL: trace from symptom to root cause — do not stop at the first plausible explanation
  • MANDATORY: if the bug is intermittent, log enough state to reproduce it deterministically before fixing
  • MUST finish collecting evidence (logs, health, recent diff, error-parser output) before forming the hypothesis — an investigation that halts at the first error found reports what the user already saw and misses the one they did not

Gotchas

  • docker compose logs with no --since shows logs from the current container lifecycle plus anything buffered. After a restart you may read stale logs that look like the current error. Always filter: docker compose logs --since 5m.
  • tail -f stops emitting after a log rotation unless you pass -F (GNU) or --follow=name — the file descriptor points at the renamed inode. On rotated logs, always use -F.
  • curl -f <url> exits non-zero on 4xx/5xx but discards the response body — you lose the exact error. Debug with curl -s -o /tmp/body -w 'HTTP %{http_code}\n' and then inspect /tmp/body.
  • Stack traces from uvicorn/gunicorn/WSGI show framework frames first; the first few frames are almost always irrelevant. Scroll past framework internals and find the first frame inside your own package.
  • A 500 with "Internal Server Error" and no body usually means the error happened before the logger was initialized — check service start-up logs, not request logs.

When NOT to Use

  • For triaging an unreported bug without a known symptom — use /triage-issue instead
  • For writing a fix once the cause is already known — use /fix
  • For performance-specific investigation — use /performance-profiling or /analyze --type=complexity
  • For a live production incident — use /workflow incident-response (coordinated response)
  • Bug fixed? → /review to verify the fix quality
  • Need a regression test? → /tdd to write it test-first
  • Performance issue? → /analyze --type=complexity for hotspot analysis
  • Incident in production? → /workflow incident-response for full response

© softspark, 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

SKILL.md and 1 other file (scripts) in app/skills/debug of softspark/ai-toolkit.

  • SKILL.md
  • scripts/error-parser.py

Open the folder on GitHubat commit d64db2b

Compare with similar skills

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

Debug compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debug this skillsoftspark/ai-toolkit179—~2.1kAutomated safety check: NotesApache-2.0
OpenLogi macOS Permissions TriageAprilNEA/OpenLogi23k—~2.5kAutomated safety check: NotesApache-2.0
Bug Finder for daisyUIsaadeghi/daisyui43k—~2.3kAutomated safety check: PassMIT
Root Cause Debugginggarrytan/gstack136k—~1.4kAutomated safety check: PassMIT
Graph-Based Bug Tracingtirth8205/code-review-graph32k1 repos~287Automated safety check: PassMIT
Systematic DebuggingChrisWiles/claude-code-showcase6.1k3 repos~1.2kAutomated safety check: PassNone

Similar skills

  • OpenLogi macOS Permissions Triage

    AprilNEA/OpenLogi

    Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated 4 days ago
    DevelopmentAuto-check: notes

  • Bug Finder for daisyUI

    saadeghi/daisyui

    Investigates suspected bugs in the daisyUI monorepo through read-only analysis, then writes a decision-ready fix plan in tmp/bugs without changing any product code.

    43k GitHub stars~2.3k tokensUpdated 8 days ago
    DevelopmentAuto-check passed

  • Root Cause Debugging

    garrytan/gstack

    Investigates bugs, errors and stack traces in phases and requires a root-cause hypothesis to be confirmed before any fix is written.

    136k GitHub stars~1.4k tokensUpdated today
    DevelopmentAuto-check passed

  • Graph-Based Bug Tracing

    tirth8205/code-review-graph

    Traces a bug through a code knowledge graph, following callers, callees and execution flow before opening source files, within a small token budget.

    32k GitHub starsUsed in 1 repo~287 tokens
    DevelopmentAuto-check passed

  • Systematic Debugging

    ChrisWiles/claude-code-showcase

    Applies a four-phase debugging routine that finds the root cause of a bug or failing test before any fix is written.

    6.1k GitHub starsUsed in 3 repos~1.2k tokens
    DevelopmentAuto-check passed

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

    103k GitHub starsUsed in 1 repo~2.6k tokens
    DevelopmentAuto-check passed

More from softspark/ai-toolkit

All 112 skills in this repo

  • Prepare Test Env

    softspark/ai-toolkit

    Prepare or verify a project QA environment with source identity, readiness, browser access, evidence paths and owned cleanup.

    179 GitHub stars~1.8k tokensUpdated yesterday
    Auto-check: notes

  • A11y Validate

    softspark/ai-toolkit

    Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. An agent skill from softspark/ai-toolkit.

    179 GitHub stars~3.8k tokensUpdated yesterday
    Auto-check: notes

  • Analyze

    softspark/ai-toolkit

    Analyzes code quality, complexity, patterns across codebase.

    179 GitHub stars~1k tokensUpdated yesterday
    Auto-check passed

  • Autonomous Dev

    softspark/ai-toolkit

    Drives a brief, specification, issue or existing PR through implementation, review, tests and QA to a ready PR.

    179 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check: notes

  • Brand Voice

    softspark/ai-toolkit

    Direct technical voice for docs, README, user-facing text. An agent skill from softspark/ai-toolkit.

    179 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed

  • CI

    softspark/ai-toolkit

    Detect/generate/debug CI pipeline config (GitHub Actions, GitLab CI).

    179 GitHub stars~1.1k tokensUpdated yesterday
    Auto-check: notes

Categories

Questions about Debug

What does Debug do?

Systematic debugging via logs, health checks, hypothesis-driven investigation. Debug is an agent skill from softspark/ai-toolkit. Systematic debugging via logs, health checks, hypothesis-driven investigation.

When should I use Debug?

Debug fits situations like: tasks that involve Debugging; tasks that involve Root cause analysis.

How do I install Debug in Claude Code?

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

How do I install Debug in Codex?

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

Can I use Debug 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 softspark/ai-toolkit --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 Debug need to run?

Going by SKILL.md and its folder, Debug needs Python for the scripts in its folder and the command-line tools its instructions call (docker, curl, python3, redis-cli, python and java). Our summary lists: Python 3; Node.js; Docker. Its frontmatter pre-approves these tools: Bash, Read, Grep.

Does Debug access the network?

SKILL.md contains no URLs. Its commands use docker, curl and git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Debug 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Debug use?

Debug 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 Debug use?

About 2.1k tokens (SKILL.md is roughly 8.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 Debug?

Skills that share tags, products or a category with Debug: OpenLogi macOS Permissions Triage (AprilNEA/OpenLogi, 23k stars), Bug Finder for daisyUI (saadeghi/daisyui, 43k stars), Root Cause Debugging (garrytan/gstack, 136k stars) and Graph-Based Bug Tracing (tirth8205/code-review-graph, 32k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug?

softspark (a GitHub user) maintains it in softspark/ai-toolkit, which has 179 GitHub stars. The repository holds 112 skills in this directory. The repository was last updated on October 7, 2026.

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