How do I install the Troubleshoot skill?

Run npx skillmds@latest add majiayu000/troubleshoot-3 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Troubleshoot safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Troubleshoot?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Troubleshoot free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Troubleshoot?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Troubleshoot by majiayu000 — Agent Skill

Name: Troubleshoot
Rating: 4.2 (5 reviews)
Author: majiayu000

File contents

Troubleshoot: $ARGUMENTS

Unlike /fix-issue (code-level bugs), /troubleshoot investigates runtime/production problems from symptoms.

Step 1 — Gather Symptoms

Identify what's happening:

What errors are users seeing? (status codes, error messages)
When did it start? (after a deploy, config change, or spontaneously?)
Is it affecting all requests or specific endpoints?
Is the health endpoint responding? What status?

Step 2 — Check Infrastructure

# Is the process running? Hit the health endpoint (see project config for URL)
# Check external resource connectivity via device/info endpoint
# Check recent logs — look for ERROR and WARNING entries

Common infrastructure issues:

See the Troubleshooting table in the project config for common symptoms, likely causes, and checks.

Step 3 — Check Configuration

Read the config file and verify env vars are set correctly. See the Environment Variables table in the project config for all settings and their defaults. Common misconfigurations:

Mock mode accidentally enabled in production
Resource identifiers don't match actual hardware
API key not set when it should be
Rate limit too restrictive

Step 4 — Check Application Logs

Look for patterns in log output:

Audit logger entries — are state changes being logged?
WARNING level — resource disconnection, degraded mode
ERROR level — communication failures, unhandled exceptions
Startup messages — did all components initialize?

Step 5 — Reproduce Locally

# Start in mock/dev mode to isolate hardware vs software issues (see dev run command in project config)
# Hit the failing endpoint

If it works in mock mode → hardware/external resource issue
If it fails in mock mode → software bug → switch to /fix-issue

Step 6 — Resolution

If config issue → fix env vars, restart
If hardware/resource issue → check connection, permissions, drivers
If software bug → use /fix-issue to fix the code
If performance issue → use /optimize to profile and fix

Step 7 — Document

Log the incident:

What happened, when, how long it lasted
Root cause identified
Fix applied
Prevention steps (monitoring, alerting, tests)

---name: troubleshoot-3description: Investigate runtime or production issues from logs, errors, or unexpected behavior (Marcus + Alex workflow)--- Troubleshoot: $ARGUMENTS Unlike `/fix-issue` (code-level bugs), `/troubleshoot` investigates runtime/production problems from symptoms. ## Step 1 — Gather Symptoms Identify what's happening: - What errors are users seeing? (status codes, error messages) - When did it start? (after a deploy, config change, or spontaneously?) - Is it affecting all requests or specific endpoints? - Is the health endpoint responding? What status? ## Step 2 — Check Infrastructure ```bash # Is the process running? Hit the health endpoint (see project config for URL) # Check external resource connectivity via device/info endpoint # Check recent logs — look for ERROR and WARNING entries ``` ### Common infrastructure issues: See the Troubleshooting table in the project config for common symptoms, likely causes, and checks. ## Step 3 — Check Configuration Read the config file and verify env vars are set correctly. See the Environment Variables table in the project config for all settings and their defaults. Common misconfigurations: - Mock mode accidentally enabled in production - Resource identifiers don't match actual hardware - API key not set when it should be - Rate limit too restrictive ## Step 4 — Check Application Logs Look for patterns in log output: - Audit logger entries — are state changes being logged? - `WARNING` level — resource disconnection, degraded mode - `ERROR` level — communication failures, unhandled exceptions - Startup messages — did all components initialize? ## Step 5 — Reproduce Locally ```bash # Start in mock/dev mode to isolate hardware vs software issues (see dev run command in project config) # Hit the failing endpoint ``` - If it works in mock mode → hardware/external resource issue - If it fails in mock mode → software bug → switch to `/fix-issue` ## Step 6 — Resolution - If config issue → fix env vars, restart - If hardware/resource issue → check connection, permissions, drivers - If software bug → use `/fix-issue` to fix the code - If performance issue → use `/optimize` to profile and fix ## Step 7 — Document Log the incident: - What happened, when, how long it lasted - Root cause identified - Fix applied - Prevention steps (monitoring, alerting, tests)

Frequently asked questions

Troubleshoot