Client troubleshooting guide builder · free AI skill

Transforms raw log snippets, error descriptions, or API call patterns into a structured client-facing troubleshooting guide with a symptom summary, a ranked list of probable causes, a step-by-step diagnostic flow…

Purpose

Turn a messy error report — log lines, a stack trace, a client's description, or an odd API call pattern — into a clean, sequenced troubleshooting guide that a support engineer or CSM can run without escalating. Produces a diagnostic decision flow, resolution steps mapped to each probable cause, and a ready-to-send client reply, so recurring issues become reusable runbooks instead of one-off firefights.

When to Use

Invoke this skill when the user asks to:

Build a troubleshooting guide or runbook from an error, log snippet, or stack trace
Turn a recurring support ticket into reusable documentation
Diagnose an API error (4xx/5xx), webhook failure, or authentication/token issue
Document a step-by-step diagnostic flow for a client-facing support team
Create a decision tree for triaging a specific integration or SDK problem
Write a client-facing explanation of what went wrong and how to fix it

Inputs Required

Before starting, collect:

The error signal: Log snippet, error message, status code, stack trace, or client's verbatim description
Product area: What the client was doing — e.g., authentication, webhooks, rate limits, SDK call, data sync
Environment details: Language/SDK, API version, sandbox vs. production, region if relevant
What the client already tried: Steps taken, if known
Access level of the guide's user: Client-facing (limited access) vs. internal support (dashboard/logs access)
Known related issues: Any recurring causes or recent incidents tied to this symptom
Escalation path: Who owns L2/engineering escalation and what triggers it

If access level or escalation path is missing, default to a client-facing guide and a generic "escalate to L2 with reproduction steps" criterion, and note the assumption.

Instructions

Step 1: Symptom Summary

Restate the problem in one clear paragraph a non-author could understand.

Extract the observable symptom (what the client sees) separately from the technical signal (what the log/error says)
Identify the status code or error class if present, and translate it into plain language (e.g., 401 → "the request was authenticated incorrectly or the token expired")
Note the trigger context: when it happens, how often, and whether it's intermittent or consistent
If the error signal is ambiguous, list the 1–2 clarifying questions that would most narrow the cause

Step 2: Probable Causes (Ranked by Likelihood)

Generate 3–6 probable causes, ordered most-to-least likely for this specific signal. For each cause include:

Cause name: Short, specific (e.g., "Expired or malformed bearer token," not "Auth problem")
Why it fits this signal: One sentence tying it to the error/log evidence
Likelihood: High / Medium / Low, with a one-line reason
Fastest confirming check: The single test that proves or rules this cause in

Rank by a combination of frequency (how common this cause is for this error class) and evidence match (how well the signal points to it). Put the highest-frequency, best-matched cause first.

Step 3: Diagnostic Flow (Step-by-Step Decision Tree)

Build a sequential yes/no diagnostic flow that isolates the cause in the fewest steps.

Start with the cheapest, highest-yield check first (e.g., verify the token isn't expired before inspecting payload structure)
Format each node as: Check → Expected result → If yes, go to X / If no, go to Y
Every branch must terminate at either a confirmed cause (route to its resolution in Step 4) or an escalation trigger (route to Step 5)
Include the exact command, dashboard location, or API call to run at each check where possible (e.g., "Run a test request with curl -H 'Authorization: Bearer <token>' and confirm a 200")
Keep it to 4–8 decision nodes — collapse redundant branches

Step 4: Resolution Steps (Per Confirmed Cause)

For each probable cause from Step 2, provide a numbered fix sequence.

Write steps at the access level specified — client-facing guides never instruct actions the client can't perform
Each resolution: numbered steps, the expected outcome after the fix, and a verification step confirming the issue is resolved
Include a rollback or safe-retry note where a fix could cause side effects (e.g., regenerating an API key invalidates the old one)
Flag any fix that requires a code change vs. a config/dashboard change

Step 5: Escalation Criteria

Define exactly when to stop troubleshooting and escalate.

List 3–5 concrete triggers (e.g., "diagnostic flow terminates with no confirmed cause," "error persists after token regeneration and payload validation," "5xx errors correlate with a platform status incident")
Specify what to include in the escalation: reproduction steps, request ID / trace ID, timestamps, environment, and confirmed-ruled-out causes
Name the escalation owner or path from the input (or the default note if not provided)

Step 6: Client-Ready Reply

Write a copy-paste response the support team can send to the client.

Plain, reassuring, no internal jargon or blame
Structure: acknowledge → likely cause in plain terms → 1–3 client-actionable steps → what happens next if that doesn't work
Under 150 words; no bracket placeholders — fill in the specifics from the inputs

Output Format

Structure: Six labeled sections in order; diagnostic flow as an indented decision tree; resolution steps as numbered lists grouped by cause
Length: 800–1,200 words
Format: Structured document — scannable headers, numbered flows, inline code formatting for commands and error codes
Sections: Symptom Summary → Probable Causes (ranked) → Diagnostic Flow → Resolution Steps → Escalation Criteria → Client-Ready Reply
Tone: Support engineer writing a runbook — precise, calm, action-first; no filler, no hedging

Quality Checklist

Before delivering output, verify:

[ ] Probable causes are ranked by likelihood with a stated reason — not an unordered list
[ ] Every diagnostic flow branch terminates at either a confirmed cause or an escalation trigger (no dead ends)
[ ] Each resolution set includes a verification step confirming the fix worked
[ ] Resolution steps match the specified access level — client-facing guides contain no admin-only actions
[ ] Escalation criteria are concrete triggers, not "escalate if needed," and specify what to include
[ ] The client-ready reply is under 150 words with zero bracket placeholders

Notes

Ask for a request ID or trace ID early — it's the single highest-leverage piece of evidence for API issues and it's what engineering will ask for first
For intermittent errors, prioritize causes tied to rate limits, token expiry windows, and eventual-consistency delays before assuming a code bug
The best guides get shorter over time: once a cause proves rare in practice, demote or drop it so the flow stays fast
When the error signal is a raw stack trace, isolate the topmost line originating in the client's own code versus the SDK/platform — that boundary usually points to who owns the fix

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
<your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

Drag this file into a new chat, or copy and paste its contents
Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills