Troubleshooting Guide

Creates structured troubleshooting documentation with a diagnostic-first approach. You'd use this for FAQ pages, known issues lists, error code references, or any documentation meant to help users resolve problems quickly. The template puts quick health checks up front before diving into specific issues, which is smart because it gets people to the "is it even running" questions first. Each issue gets its own reference guide with verbatim error messages and step-by-step diagnostics. The best practices section emphasizes showing actual vs expected output and testing your solutions, which sounds obvious but gets skipped constantly in real troubleshooting docs.

skills.sh installs: 447
GitHub stars: 379
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add aj-geddes/useful-ai-prompts --skill troubleshooting-guide --agent claude-code

Installs into .claude/skills of the current project.

Files

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

# Troubleshooting Guide

## Quick Diagnosis

### Is the Service Working?

Check our [Status Page](https://status.example.com) first.

### Quick Health Checks

```bash
# 1. Check service is running
curl https://api.example.com/health

# 2. Check your API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
  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:

SKILL.md on GitHub