debugging-strategies
Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
About this skill
This skill equips AI agents with a comprehensive toolkit for effective debugging, moving beyond trial-and-error to systematic problem-solving. It integrates proven strategies, powerful diagnostic tools, and methodical approaches to efficiently identify, analyze, and resolve software issues. By guiding the agent through structured debugging workflows, this skill helps in tracking elusive bugs, investigating performance bottlenecks, analyzing crash data, and addressing incidents in complex and distributed systems, ensuring a more reliable and efficient development and operational environment.
Best use case
Systematic identification and resolution of software bugs, performance bottlenecks, and operational incidents across various environments, including analyzing crash data and distributed system failures.
Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
Expedited resolution of software defects, clearer identification of root causes, enhanced system stability, and a structured, methodical approach to debugging that minimizes trial-and-error.
Practical example
Example input
I'm encountering an intermittent bug in my Python application where users occasionally report 'Connection Refused' errors, but it's not consistently reproducible. I've checked the database connection string and firewall rules, but nothing seems out of place. Can you help me systematically debug this?
Example output
To systematically approach this intermittent 'Connection Refused' error, let's follow a structured debugging process:
1. **Reproducibility:** Although intermittent, can we identify specific conditions (e.g., peak load, certain user actions, specific time of day) that increase the likelihood of the error?
2. **Environment Analysis:** Confirm the exact environment (OS, Python version, library versions) where the error occurs. Is it consistent across environments (dev, staging, prod)?
3. **Logging & Monitoring:** Have you implemented comprehensive logging around connection attempts, successes, and failures? Are there any relevant logs from the database server or other services your application communicates with? We should look for specific error codes or messages.
4. **Network Diagnostics:** Since it's 'Connection Refused', this often points to a network or port issue.
* Verify the application can reach the database host and port using `telnet` or `nc` from the application server.
* Check database server logs for rejected connections.
* Are there any load balancers, proxies, or firewalls between the application and the database that might be intermittently dropping connections or rate-limiting?
5. **Resource Exhaustion:** Could it be temporary resource exhaustion (e.g., too many open connections, out of memory on the database server or application server) that causes the refusal? Monitor CPU, memory, and open file descriptors.
6. **Dependency Checks:** Are there any other services or components that the application relies on before connecting to the database? Check their health.
Let's start by enhancing logging around the connection attempt and observing if any patterns emerge from the system logs during an error occurrence.When to use this skill
- Tracking down elusive bugs
- Investigating performance issues
- Debugging production incidents
- Analyzing crash dumps or stack traces
When not to use this skill
- There is no reproducible issue or observable symptom
- The task is purely feature development
- You cannot access logs, traces, or runtime signals
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debugging-strategies/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debugging-strategies Compares
| Feature / Agent | debugging-strategies | Standard Approach |
|---|---|---|
| Platform Support | Claude | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | easy | N/A |
Frequently Asked Questions
What does this skill do?
Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
Which AI agents support this skill?
This skill is designed for Claude.
How difficult is it to install?
The installation complexity is rated as easy. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Debugging Strategies Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches. ## Use this skill when - Tracking down elusive bugs - Investigating performance issues - Debugging production incidents - Analyzing crash dumps or stack traces - Debugging distributed systems ## Do not use this skill when - There is no reproducible issue or observable symptom - The task is purely feature development - You cannot access logs, traces, or runtime signals ## Instructions - Reproduce the issue and capture logs, traces, and environment details. - Form hypotheses and design controlled experiments. - Narrow scope with binary search and targeted instrumentation. - Document findings and verify the fix. - If detailed playbooks are required, open `resources/implementation-playbook.md`. ## Resources - `resources/implementation-playbook.md` for detailed debugging patterns and checklists.
Related Skills
n8n-expression-syntax
Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows.
mermaid-expert
Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling.
mcp-builder-ms
Use this skill when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
makepad-deployment
CRITICAL: Use for Makepad packaging and deployment. Triggers on: deploy, package, APK, IPA, 打包, 部署, cargo-packager, cargo-makepad, WASM, Android, iOS, distribution, installer, .deb, .dmg, .nsis, GitHub Actions, CI, action, marketplace
macos-menubar-tuist-app
Build, refactor, or review SwiftUI macOS menubar apps that use Tuist.
kaizen
Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.
issues
Interact with GitHub issues - create, list, and view issues.
hugging-face-tool-builder
Your purpose is now is to create reusable command line scripts and utilities for using the Hugging Face API, allowing chaining, piping and intermediate processing where helpful. You can access the API directly, as well as use the hf command line tool.
git-pushing
Stage all changes, create a conventional commit, and push to the remote branch. Use when explicitly asks to push changes ("push this", "commit and push"), mentions saving work to remote ("save to github", "push to remote"), or completes a feature and wants to share it.
git-hooks-automation
Master Git hooks setup with Husky, lint-staged, pre-commit framework, and commitlint. Automate code quality gates, formatting, linting, and commit message enforcement before code reaches CI.
gh-review-requests
Fetch unread GitHub notifications for open PRs where review is requested from a specified team or opened by a team member. Use when asked to "find PRs I need to review", "show my review requests", "what needs my review", "fetch GitHub review requests", or "check team review queue".
fp-types-ref
Quick reference for fp-ts types. Use when user asks which type to use, needs Option/Either/Task decision help, or wants fp-ts imports.