Agent skill · writing content · aj-geddes
troubleshooting-guide
Create comprehensive troubleshooting guides, FAQ documents, known issues lists, and debug guides. Use when documenting common problems, error messages, or debugging procedures.
Why this skill is useful
Codifies a structured approach to creating troubleshooting documentation that the AI could infer but now doesn't have to guess.
What it needs
About 1k tokens when loaded. Last updated 2026-03-04. 307 stars on the source repository.
What this skill does
Troubleshooting Guide Table of Contents Overview When to Use Quick Start Reference Guides Best Practices Overview Create structured troubleshooting documentation that helps users and support teams quickly diagnose and resolve common issues. When to Use FAQ documentation Common error messages Debug guides Known issues lists Error code reference Performance troubleshooting Configuration issues Installation problems Quick Start Installation problems bash 1. Check service is running curl https://api.example.com/health 2. Check your API key curl -H "Authorization: Bearer YOURAPIKEY" \ https://api.example.com/api/v1/status 3. Check network connectivity ping api.example.com 4. Check DNS resolution nslookup api.example.com Reference Guides Detailed implementations in the references/` directory: Guide Contents --- --- Issue: "Authentication Failed" Issue: "Authentication Failed" Issue: "Rate Limit Exceeded" Issue: "Rate Limit Exceeded" Issue: "Connection Timeout" Issue: "Connection Timeout" Issue: "Invalid JSON Response" Issue: "Invalid JSON Response" Issue: "Slow Performance" Issue: "Slow Performance" Best Practices ✅ DO Start with most common issues Include error messages verbatim Provide step-by-step diagnostics Show expected vs actual output Include code examples Document error codes Add screenshots/videos Link to related documentation Keep solutions up-to-date Include workarounds Test all solutions ❌ DON'T Use vague descriptions Skip diagnostic steps Forget to show examples Assume technical knowledge Skip verification steps Forget edge cases
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/troubleshooting-guide