Skills: Debugging Skills
Last updated: 2026-08-31
Debugging is the most time-consuming part of development — Skills codify debugging experience so every troubleshooting session has a method to follow.
1. Debugging Skill Types
(1) Error Diagnosis
Locate root causes from error messages:
YAML
---
name: error-diagnoser
description: "Diagnose root causes from error messages"
triggers:
- keyword: "error|bug|exception"
tools:
- Read
- Grep
- Glob
- Bash
---
(2) Performance Analysis
Locate performance bottlenecks:
| Analysis Dimension | Tool/Method | Output |
|---|---|---|
| CPU hotspots | Profiler output | Function time ranking |
| Memory leaks | Memory snapshot comparison | Leaked object location |
| Slow queries | SQL log analysis | Slow query list |
| Startup time | Timestamp instrumentation | Time distribution by phase |
(3) Log Analysis
Extract key clues from logs:
MARKDOWN
## Log Analysis Flow
1. Read log file
2. Grep for ERROR/WARN keywords
3. Extract exception stacks and timeline
4. Correlate log entries for the same request
5. Output analysis report
2. Systematic Debugging Process
(1) Four-Phase Debugging Method
TEXT
📖 Display only
Debugging Four Phases
├── 1. Reproduce
│ ├── Confirm error is reproducible
│ ├── Record reproduction steps
│ └── Narrow reproduction conditions
├── 2. Locate
│ ├── Read error stack trace
│ ├── Search related code
│ └── Confirm problem location
├── 3. Fix
│ ├── Analyze root cause
│ ├── Write fix code
│ └── Add defensive checks
└── 4. Verify
├── Reproduction scenario passes
├── Run full test suite
└── Confirm no regression
(2) Binary Search Localization
MARKDOWN
## Binary Search Debugging
1. Confirm the version range where the problem exists
2. Bash: git bisect start
3. Narrow range to a specific commit step by step
4. Read the diff for that commit
5. Locate the specific code line that introduced the problem
(3) Hypothesis-Driven Debugging
MARKDOWN
## Hypothesis Verification Method
1. List possible cause hypotheses (max 3)
2. Design a verification method for each hypothesis
3. Verify from highest to lowest probability
4. Verification passes → Confirm root cause
5. Verification fails → Eliminate hypothesis, re-analyze
3. Common Error Patterns
(1) Error Pattern Quick Reference
| Error Type | Typical Characteristics | Investigation Direction |
|---|---|---|
| Null pointer | NoneType/null/undefined |
Check variable assignment chain |
| Type error | TypeError/ClassCastException |
Check type conversions and assertions |
| Concurrency | Intermittent failures | Check shared state and locks |
| Boundary | Only fails with specific input | Check null, zero, extreme values |
| Environment diff | Works locally, fails in production | Check config, dependency versions |
| Timing | Order-dependent | Check async operations and event order |
(2) Error Message Interpretation
TEXT
📖 Display only
Error stack reading order:
1. Last line: Error type and message (most critical)
2. 2nd-3rd from bottom: Call sites in your code
3. Higher frames: Framework/library call chain
4. First non-framework line: The actual trigger point
4. Debugging Skill Practice
▶ Example: Smart Diagnosis Skill
Alice created a Skill that automatically diagnoses errors:
YAML
---
name: smart-debug
description: "Systematic debugging: reproduce→locate→fix→verify"
tools:
- Read
- Grep
- Glob
- Bash
- Edit
---
MARKDOWN
## Debugging Flow
1. Read error message and stack trace
2. Grep to find where the error message appears in code
3. Read related code, analyze possible causes
4. List 3 hypotheses and verify one by one
5. After confirming root cause, Edit to fix
6. Bash to run tests for verification
Bob said: "The biggest fear in debugging is 'just try it' — fixing something without knowing why it worked means you'll make the same mistake again. Skills enforce the hypothesis→verification flow so every step has a reasoned basis."
❓ FAQ
Q Is AI debugging faster than manual?
A Much faster for patterned errors (null pointers, type errors, common exceptions). For complex business logic issues, AI can narrow the scope but final diagnosis still needs human input.
Q How to prevent AI from giving wrong debugging directions?
A Require AI to list hypotheses and verify one by one, rather than jumping to conclusions. Verify every step of the reasoning chain.
Q Does a debugging Skill need edit permissions?
A Diagnosis phase only needs read access. Fix phase requires Edit. We recommend splitting into two Skills: diagnosis (read-only) + fix (read-write).
📖 Summary
- Three debugging Skill types: error diagnosis, performance analysis, log analysis
- Four-phase process: Reproduce → Locate → Fix → Verify
- Localization methods: stack analysis, binary search, hypothesis verification
- Core principle: Understand before acting; hypothesis-driven, not blind trial-and-error
📝 Exercises
- Basic (⭐): Create an error diagnosis Skill that can auto-locate code positions from error stacks.
- Intermediate (⭐⭐): Create a systematic debugging Skill implementing the four-phase method with hypothesis verification.
- Advanced (⭐⭐⭐): Create a performance analysis Skill that locates bottlenecks from profiler output, providing optimization suggestions and estimated gains.
