{"id":"75530cfe-6019-41eb-8558-413a5ba77e06","shortId":"smuhsd","kind":"skill","title":"Troubleshooting Guide Builder","tagline":"Builds a structured troubleshooting guide with symptom → cause → fix format for any tool or system.","description":"# Troubleshooting Guide Builder\n\n## What this skill does\n\nThis skill builds a structured troubleshooting guide that maps symptoms to causes to fixes for any software tool, API, or system. Each entry follows a consistent format: what the user experiences, why it happens, and exactly how to fix it — including specific commands, configuration changes, or code snippets. The result is a guide that developers or support staff can scan quickly to resolve issues without digging through source code or guessing.\n\nUse this when writing documentation for a new tool, after an incident reveals a common failure mode, when your support team keeps answering the same questions, or when preparing runbooks for operational issues.\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/troubleshooting-guide-builder/SKILL.md` in your project root.\n\nThen ask:\n- *\"Use the Troubleshooting Guide Builder skill to write a troubleshooting guide for our CLI tool.\"*\n- *\"Build a troubleshooting guide for the most common deployment errors using the Troubleshooting Guide Builder skill.\"*\n\nProvide:\n- A description of the tool, API, or system\n- A list of known issues, error messages, or symptoms (ideally from real support cases)\n- Any relevant error codes, configuration options, or environment details\n\n### Cursor\n\nAdd the instructions below to your `.cursorrules` or paste them into the Cursor AI pane. Provide the tool description and known issues.\n\n### Codex\n\nPaste the tool description, error messages, and any existing support notes. Ask Codex to follow the instructions below.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to build a troubleshooting guide, follow these steps:\n\n### Step 1 — Gather known issues\n\nIf given a list of symptoms or errors, use them as the basis. If not, generate a comprehensive list of likely issues by thinking through:\n- Installation and setup failures\n- Authentication and permissions errors\n- Configuration mistakes\n- Rate limits and quota errors\n- Network and connectivity issues\n- Common misunderstandings about how the tool works\n- Environment-specific issues (OS, version, dependencies)\n- Data format or validation errors\n\n### Step 2 — For each issue, define the three parts\n\nEvery troubleshooting entry must have:\n\n1. **Symptom** — What does the user actually see? Use the exact error message if possible. Be specific: \"The command exits with code 1 and prints `Error: ECONNREFUSED`\" is better than \"it doesn't work.\"\n\n2. **Cause** — Why does this happen? This is the technical explanation. Keep it brief (1–3 sentences) but accurate enough that an informed reader understands the underlying mechanism.\n\n3. **Fix** — The exact steps to resolve it. Use numbered steps for multi-step fixes. Include specific commands, file paths, config values, or code snippets. The fix must be actionable — not \"check your configuration\" but \"open `~/.config/tool.json` and ensure `timeout` is set to a value greater than 0.\"\n\n### Step 3 — Add diagnostic steps where needed\n\nFor issues where the fix isn't the same for everyone, add a diagnostic section before the fix:\n\n```\n**How to diagnose**: Run `tool --verbose` and look for the line starting with \"Connection\". If it shows \"refused\", the server is not running. If it shows \"timeout\", the server is running but unreachable.\n```\n\n### Step 4 — Organize by category\n\nGroup issues into logical categories. Common categories:\n- Installation & Setup\n- Authentication & Permissions\n- Configuration\n- Network & Connectivity\n- Rate Limits & Quotas\n- Data & Input Errors\n- Performance\n- Common Misunderstandings\n\n### Step 5 — Format the guide\n\n```markdown\n# Troubleshooting Guide — [Tool/System Name]\n\n## Quick Reference\n\n| Symptom | Section |\n|---------|---------|\n| [Short symptom description] | [Category] |\n| ... | ... |\n\n---\n\n## [Category Name]\n\n### [Short symptom title]\n\n**Symptom**\n[Exact error message or description of what the user sees]\n\n**Cause**\n[Brief technical explanation of why this happens]\n\n**Fix**\n1. [Step 1]\n2. [Step 2]\n\n[or for single-step: just the fix as a paragraph or code block]\n\n**Still not working?**\n[Optional: what to check next or where to get help]\n\n---\n\n[Repeat for each issue]\n```\n\n### Step 6 — Include a \"Before You Start\" section\n\nAt the top, add a short section with universal first steps that resolve many issues:\n- Check the current version: `tool --version`\n- Check the logs: where are they?\n- Enable verbose mode: how?\n- Verify the environment: key environment variables to check\n\n## Example\n\n**Input to Agent:**\n> \"Use the Troubleshooting Guide Builder skill for our CLI deployment tool called `deploytool`. Known issues from support:\n> 1. Deploy hangs forever\n> 2. 'Invalid credentials' error even with correct API key\n> 3. 'Region not found' error\n> 4. Deployed version doesn't match local version\"\n\n**Output from Agent:**\n\n> # Troubleshooting Guide — deploytool\n>\n> ## Before You Start\n>\n> Run these commands before diving into specific issues:\n> ```bash\n> deploytool --version          # Check you're on the latest version\n> deploytool config show        # Review current configuration\n> deploytool deploy --verbose   # Enable verbose logs for your next deploy\n> ```\n>\n> ---\n>\n> ## Authentication\n>\n> ### \"Invalid credentials\" error even with the correct API key\n>\n> **Symptom**\n> ```\n> Error: Invalid credentials. Check your DEPLOYTOOL_API_KEY.\n> ```\n>\n> **Cause**\n> The API key is read from the `DEPLOYTOOL_API_KEY` environment variable. If the variable is set in a `.env` file but the file isn't loaded, or if the variable name has a typo, the tool falls back to an empty string and authentication fails.\n>\n> **Fix**\n> 1. Confirm the variable is set: `echo $DEPLOYTOOL_API_KEY`\n> 2. If empty, export it: `export DEPLOYTOOL_API_KEY=your_key_here`\n> 3. Verify it's the correct key in your [dashboard](https://example.com/dashboard)\n> 4. If using a `.env` file, ensure your shell loads it: `source .env`\n>\n> ---\n>\n> ## Deployment Issues\n>\n> ### Deploy hangs and never completes\n>\n> **Symptom**\n> The `deploytool deploy` command starts but never finishes, even after several minutes.\n>\n> **Cause**\n> The tool waits for a health check response from the deployed service. If the service fails to start or the health check endpoint isn't reachable, the deploy hangs until a 10-minute timeout.\n>\n> **How to diagnose**\n> Run with `--verbose` and look for \"Waiting for health check at...\". Navigate to that URL in a browser — if it returns an error, your application failed to start.\n>\n> **Fix**\n> 1. Check your application logs: `deploytool logs --tail 50`\n> 2. Fix the application error causing startup failure\n> 3. Re-deploy: `deploytool deploy`\n>\n> If your service intentionally has no health check: `deploytool deploy --no-health-check`\n\n## Notes\n\n- Use exact error messages in the Symptom section — users search for the literal error text they see.\n- The Fix section should be written so a tired developer can follow it at 2am without thinking. Be explicit.\n- Update this guide after every incident where an issue wasn't already covered.","tags":["troubleshooting","guide","builder","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor","llm"],"capabilities":["skill","source-notysoty","skill-troubleshooting-guide-builder","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-cline","topic-cursor","topic-llm","topic-llm-skills","topic-skills"],"categories":["openagentskills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Notysoty/openagentskills/troubleshooting-guide-builder","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Notysoty/openagentskills","source_repo":"https://github.com/Notysoty/openagentskills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (7,071 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:25.202Z","embedding":null,"createdAt":"2026-05-18T13:20:47.315Z","updatedAt":"2026-05-18T19:13:25.202Z","lastSeenAt":"2026-05-18T19:13:25.202Z","tsv":"'/.config/tool.json':449 '/dashboard)':865 '0':460 '1':269,350,372,398,590,592,695,831,966 '10':931 '2':337,384,593,595,699,841,975 '2am':1035 '3':399,412,462,708,853,983 '4':520,713,866 '5':548 '50':974 '6':628 'accur':402 'action':442 'actual':356 'add':211,463,479,638 'agent':257,677,723 'agents/skills/troubleshooting-guide-builder/skill.md':140 'ai':224 'alreadi':1051 'answer':119 'api':44,184,706,772,781,785,792,839,848 'applic':961,969,978 'ask':146,245,259 'authent':302,533,764,828 'back':822 'bash':738 'basi':285 'better':378 'block':609 'brief':397,582 'browser':954 'build':4,28,162,261 'builder':3,21,151,176,682 'call':689 'case':200 'categori':523,528,530,564,565 'caus':11,37,385,581,783,899,980 'chang':70 'check':444,616,650,656,673,741,778,906,921,946,967,996,1002 'claud':133 'cli':160,686 'cline':135 'code':72,94,134,204,371,436,608 'codex':233,246 'command':68,368,430,732,890 'common':111,169,317,529,545 'complet':885 'comprehens':290 'config':433,749 'configur':69,205,306,446,535,753 'confirm':832 'connect':315,499,537 'consist':51 'copi':136 'correct':705,771,858 'cover':1052 'credenti':701,766,777 'current':652,752 'cursor':210,223 'cursorrul':217 'dashboard':862 'data':331,541 'defin':341 'depend':330 'deploy':170,687,696,714,755,763,879,881,889,910,927,986,988,998 'deploytool':690,726,739,748,754,780,791,838,847,888,971,987,997 'descript':180,229,237,563,575 'detail':209 'develop':80,1030 'diagnos':488,936 'diagnost':464,481 'dig':91 'dive':734 'document':101 'doesn':381,716 'echo':837 'econnrefus':376 'empti':825,843 'enabl':662,757 'endpoint':922 'enough':403 'ensur':451,872 'entri':48,347 'env':803,870,878 'environ':208,325,668,670,794 'environment-specif':324 'error':171,192,203,238,280,305,312,335,361,375,543,572,702,712,767,775,959,979,1006,1017 'even':703,768,895 'everi':345,1044 'everyon':478 'exact':61,360,415,571,1005 'exampl':674 'example.com':864 'example.com/dashboard)':863 'exist':242 'exit':369 'experi':56 'explan':394,584 'explicit':1039 'export':844,846 'fail':829,915,962 'failur':112,301,982 'fall':821 'file':138,431,804,807,871 'finish':894 'first':644 'fix':12,39,64,413,427,439,472,485,589,603,830,965,976,1022 'follow':49,248,265,1032 'forev':698 'format':13,52,332,549 'found':711 'gather':270 'generat':288 'get':621 'given':274 'greater':458 'group':524 'guess':96 'guid':2,8,20,32,78,150,157,165,175,264,551,554,681,725,1042 'hang':697,882,928 'happen':59,389,588 'health':905,920,945,995,1001 'help':622 'ideal':196 'incid':108,1045 'includ':66,428,629 'inform':406 'input':542,675 'instal':298,531 'instruct':213,250,254 'intent':992 'invalid':700,765,776 'isn':473,808,923 'issu':89,129,191,232,272,294,316,327,340,469,525,626,649,692,737,880,1048 'keep':118,395 'key':669,707,773,782,786,793,840,849,851,859 'known':190,231,271,691 'latest':746 'like':293 'limit':309,539 'line':496 'list':188,276,291 'liter':1016 'load':810,875 'local':719 'log':658,759,970,972 'logic':527 'look':493,941 'mani':648 'map':34 'markdown':552 'match':718 'mechan':411 'messag':193,239,362,573,1007 'minut':898,932 'mistak':307 'misunderstand':318,546 'mode':113,664 'multi':425 'multi-step':424 'must':348,440 'name':556,566,815 'navig':948 'need':467 'network':313,536 'never':884,893 'new':104 'next':617,762 'no-health-check':999 'note':244,1003 'number':421 'open':448 'oper':128 'option':206,613 'organ':521 'os':328 'output':721 'pane':225 'paragraph':606 'part':344 'past':219,234 'path':432 'perform':544 'permiss':304,534 'possibl':364 'prepar':125 'print':374 'project':143 'prompt':253 'provid':178,226 'question':122 'quick':86,557 'quota':311,540 'rate':308,538 're':743,985 're-deploy':984 'reachabl':925 'read':788 'reader':407 'real':198 'refer':558 'refus':503 'region':709 'relev':202 'repeat':623 'resolv':88,418,647 'respons':907 'result':75 'return':957 'reveal':109 'review':751 'root':144 'run':489,508,516,730,937 'runbook':126 'scan':85 'search':1013 'section':482,560,634,641,1011,1023 'see':357,580,1020 'sentenc':400 'server':505,514 'servic':911,914,991 'set':454,800,836 'setup':300,532 'sever':897 'shell':874 'short':561,567,640 'show':502,511,750 'singl':599 'single-step':598 'skill':24,27,152,177,683 'skill-troubleshooting-guide-builder' 'snippet':73,437 'softwar':42 'sourc':93,877 'source-notysoty' 'specif':67,326,366,429,736 'staff':83 'start':497,633,729,891,917,964 'startup':981 'step':267,268,336,416,422,426,461,465,519,547,591,594,600,627,645 'still':610 'string':826 'structur':6,30 'support':82,116,199,243,694 'symptom':10,35,195,278,351,559,562,568,570,774,886,1010 'system':18,46,186 'tail':973 'team':117 'technic':393,583 'text':1018 'think':296,1037 'three':343 'timeout':452,512,933 'tire':1029 'titl':569 'tool':16,43,105,161,183,228,236,322,490,654,688,820,901 'tool/system':555 'top':637 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'troubleshoot':1,7,19,31,149,156,164,174,263,346,553,680,724 'typo':818 'under':410 'understand':408 'univers':643 'unreach':518 'updat':1040 'url':951 'use':97,132,147,172,281,358,420,678,868,1004 'user':55,355,579,1012 'valid':334 'valu':434,457 'variabl':671,795,798,814,834 'verbos':491,663,756,758,939 'verifi':666,854 'version':329,653,655,715,720,740,747 'wait':902,943 'wasn':1049 'without':90,1036 'work':323,383,612 'write':100,154 'written':1026","prices":[{"id":"1d803ec4-ce1a-4d17-af1e-f5c35cfc0abb","listingId":"75530cfe-6019-41eb-8558-413a5ba77e06","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Notysoty","category":"openagentskills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:47.315Z"}],"sources":[{"listingId":"75530cfe-6019-41eb-8558-413a5ba77e06","source":"github","sourceId":"Notysoty/openagentskills/troubleshooting-guide-builder","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/troubleshooting-guide-builder","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:47.315Z","lastSeenAt":"2026-05-18T19:13:25.202Z"}],"details":{"listingId":"75530cfe-6019-41eb-8558-413a5ba77e06","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"troubleshooting-guide-builder","github":{"repo":"Notysoty/openagentskills","stars":8,"topics":["agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills","skills"],"license":"mit","html_url":"https://github.com/Notysoty/openagentskills","pushed_at":"2026-03-28T06:50:19Z","description":"A  community-driven library of reusable AI agent skills for Claude Code, Cursor, Codex, Cline, and more.","skill_md_sha":"4d020dc88f8f3eea0fc1fb095259d7d2d015be9f","skill_md_path":"skills/troubleshooting-guide-builder/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/troubleshooting-guide-builder"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Troubleshooting Guide Builder","description":"Builds a structured troubleshooting guide with symptom → cause → fix format for any tool or system."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/troubleshooting-guide-builder"},"updatedAt":"2026-05-18T19:13:25.202Z"}}