Code Debugging

When your experiment code breaks, this walks through a structured debugging process: categorize the error (syntax vs runtime vs logic), analyze the root cause from tracebacks, apply targeted fixes with retry logic, then reflect on what went wrong to prevent it next time. It's built around a state machine that escalates from minimal edits to full rewrites after repeated failures. The workflow handles common ML debugging scenarios like device mismatches, shape errors, and the dreaded 0% accuracy bug. Honestly, the real value is in forcing you to slow down and categorize instead of randomly tweaking code until something works.

skills.sh installs: 1.7K
GitHub stars: 459
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add lingzhi227/agent-research-skills --skill code-debugging --agent claude-code

Installs into .claude/skills of the current project.

Files

Code Debugging

Systematically debug experiment code with structured error categorization and fix strategies.

Input

$0 — Error message, stderr output, or code file with issues
$1 — Optional: the code that produced the error

References

Debug patterns and state machine: ~/.claude/skills/code-debugging/references/debug-patterns.md

Workflow

Step 1: Categorize the Error

Category	Examples	Severity
SyntaxError	Invalid syntax, indentation	Low
ImportError	Missing module, wrong name	Low
RuntimeError	Division by zero, shape mismatch	Medium
TimeoutError	Infinite loop, too slow	Medium
OutputError	Missing files, wrong format	Medium
LogicError	Wrong results, 0% accuracy	High

Step 2: Analyze Root Cause

Read the error traceback (last 1500 chars if truncated)
Identify the exact line and variable causing the error
Check for common patterns:
- Device mismatch (CPU vs GPU tensors)
- Shape mismatch in matrix operations
- Missing data normalization
- Off-by-one errors in indexing
- Incorrect loss function for task type