debugger

Q: How do I install debugger?

Run npx skills add https://github.com/zhaono1/agent-playbook --skill debugger in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debugger/ (personal) or .claude/skills/debugger/ (project).

by zhaono1Code Quality & Workflow

Advanced debugging specialist for diagnosing and resolving code issues. Use when user encounters bugs, errors, unexpected behavior, or mentions debugging.

Installs: 746
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads debugger automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Debugger

An advanced debugging specialist that helps diagnose and resolve code issues systematically.

When This Skill Activates

Activates when you:

Report an error or bug
Mention "debug this" or "help debug"
Describe unexpected behavior
Ask why something isn't working

Debugging Process

Phase 1: Understand the Problem

Reproduce the issue
- What are the exact steps to reproduce?
- What is the expected behavior?
- What is the actual behavior?
- What error messages appear?

Gather context

# Check recent changes
git log --oneline -10

# Check error logs
tail -f logs/error.log

# Check environment
env | grep -i debug

Phase 2: Isolate the Issue

Locate the error source
- Stack trace analysis
- Error code lookup
- Log correlation
Narrow down scope
- Binary search (comment out half)
- Minimize reproduction case
- Identify affected components

Phase 3: Analyze the Root Cause

Common Error Categories

Category	Symptoms	Investigation Steps
Null/Undefined	"Cannot read X of undefined"	Trace the variable origin
Type Errors	"X is not a function"	Check actual vs expected type
Async Issues	Race conditions, timing	Check promise handling, async/await
State Issues	Stale data, wrong state	Trace state mutations
Network	Timeouts, connection refused	Check endpoints, CORS, auth
Environment	Works locally, not in prod	Compare env vars, versions
Memory	Leaks, OOM	Profile memory usage
Concurrency	Deadlocks, race conditions	Check locks, shared state

Phase 4: Form Hypotheses

For each potential cause:

Form a hypothesis
Create a test to validate
Run the test
Confirm or reject

Phase 5: Fix and Verify

Implement the fix
Add logging if needed
Test the fix
Add regression test

Debugging Commands

General Debugging

# Find recently modified files
find . -type f -mtime -1 -name "*.js" -o -name "*.ts" -o -name "*.py"

# Grep for error patterns
grep -r "ERROR\|FATAL\|Exception" logs/

# Search for suspicious patterns
grep -r "TODO\|FIXME\|XXX" src/

# Check for console.log left in code
grep -r "console\.log\|debugger" src/

Language-Specific

JavaScript/TypeScript:

# Run with debug output
NODE_DEBUG=* node app.js

# Check syntax
node -c file.js

# Run tests in debug mode
npm test -- --inspect-brk

Python:

# Run with pdb
python -m pdb script.py

# Check syntax
python -m py_compile script.py

# Verbose mode
python -v script.py

Go:

# Race detection
go run -race main.go

# Debug build
go build -gcflags="-N -l"

# Profile
go test -cpuprofile=cpu.prof

Common Debugging Patterns

Pattern 1: Divide and Conquer

# When you don't know where the bug is:
def process():
    step1()
    step2()
    step3()
    step4()

# Comment out half:
def process():
    step1()
    # step2()
    # step3()
    # step4()

# If bug disappears, uncomment half of commented:
def process():
    step1()
    step2()
    # step3()
    # step4()

# Continue until you isolate the bug

Pattern 2: Add Logging

// Before (mysterious failure):
async function getUser(id: string) {
  const user = await db.find(id);
  return transform(user);
}

// After (with logging):
async function getUser(id: string) {
  console.log('[DEBUG] getUser called with id:', id);
  const user = await db.find(id);
  console.log('[DEBUG] db.find returned:', user);
  const result = transform(user);
  console.log('[DEBUG] transform returned:', result);
  return result;
}

Pattern 3: Minimal Reproduction

// Complex code with bug:
function processBatch(items, options) {
  // 100 lines of complex logic
}

// Create minimal reproduction:
function processBatch(items, options) {
  console.log('Items:', items.length);
  console.log('Options:', options);
  // Test with minimal data
  return processBatch([items[0]], options);
}

Error Message Analysis

Common Error Messages

Error	Likely Cause	Solution
`Cannot read property 'X' of undefined`	Accessing property on null/undefined	Add null check, use optional chaining
`X is not a function`	Wrong type, shadowing	Check typeof, verify import
`Unexpected token`	Syntax error	Check line before error, validate syntax
`Module not found`	Import path wrong	Check relative path, verify file exists
`EADDRINUSE`	Port already in use	Kill existing process, use different port
`Connection refused`	Service not running	Start service, check port
`Timeout`	Request too slow	Increase timeout, check network

Debugging Checklist

I can reproduce the issue consistently
I have identified the exact error location
I understand the root cause
I have a proposed fix
The fix doesn't break existing functionality
I've added a test to prevent regression

Scripts

Generate a debug report:

python3 scripts/debug_report.py --name <error-message> --output debug-report.md

References

references/checklist.md - Debugging checklist
references/patterns.md - Common debugging patterns
references/errors.md - Error message reference

FAQ

What does the debugger skill do?

Advanced debugging specialist for diagnosing and resolving code issues. Use when user encounters bugs, errors, unexpected behavior, or mentions debugging.

How do I install debugger?

Run npx skills add https://github.com/zhaono1/agent-playbook --skill debugger in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debugger/ (personal) or .claude/skills/debugger/ (project).

Which AI agents can use debugger?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is debugger safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains debugger?

It is published by zhaono1 in zhaono1/agent-playbook. It has 746 recorded installs.

More from zhaono1/agent-playbook

View all →

self-improving-agent

zhaono1/agent-playbook

Use after a failure, user correction, repeated workflow problem, or validated success reveals a reusable lesson. Captures bounded redacted candidates, runs executable behavior evals, and separates validation from application in durable guidance.

AI & Agents35.1K installs

planning-with-files

zhaono1/agent-playbook

Uses persistent markdown files for general planning, progress tracking, and knowledge storage (Manus-style workflow). Use for multi-step tasks, research projects, or general organization WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.

Code Quality & Workflow1.2K installs

security-auditor

zhaono1/agent-playbook

Security vulnerability expert covering OWASP Top 10 and common security issues. Use when conducting security audits or reviewing code for vulnerabilities.

Security1.1K installs

architecting-solutions

zhaono1/agent-playbook

Designs technical solutions and architecture. Use when user says "design solution", "architecture design", "technical design", or "方案设计" WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.

Code Quality & Workflow909 installs

skill-router

zhaono1/agent-playbook

Routes an agent request to the narrowest matching portable skill when the user asks which skill to use or needs help selecting one across supported hosts.

874 installs

workflow-orchestrator

zhaono1/agent-playbook

Coordinates multi-skill workflows and records or runs follow-up actions when the host runtime supports them. Use when completing PRD creation, implementation, or any milestone that should be evaluated for additional skills.

Productivity & Automation834 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

debugger

Install

Install

Describe the task

Review the result

SKILL.md

Debugger

When This Skill Activates

Debugging Process

Phase 1: Understand the Problem

Phase 2: Isolate the Issue

Phase 3: Analyze the Root Cause

Common Error Categories

Phase 4: Form Hypotheses

Phase 5: Fix and Verify

Debugging Commands

General Debugging

Language-Specific

Common Debugging Patterns

Pattern 1: Divide and Conquer

Pattern 2: Add Logging

Pattern 3: Minimal Reproduction

Error Message Analysis

Common Error Messages

Debugging Checklist

Scripts

References

FAQ

More from zhaono1/agent-playbook

Popular code quality & workflow skills