Troubleshoot One Step At A Time
Copy/paste this skill description and instructions into your Knowledge Agent's Operator Mode to configure a Guru Knowledge Agent skill that turns troubleshooting into a conversation instead of a wall of text. It confirms the symptom, asks only for the details it actually needs, then gives one step at a time and waits to hear what happened. Every session ends somewhere real — resolved, written up as a ticket, or escalated with the context already assembled.
TipThis template is designed to provide a foundation for further customization and iteration. It is not intended to be an out-of-the-box solution. Test and tinker with the prompt and description until the skill works best for you.
Skill Description
Use this skill when someone reports that something is not working and needs help diagnosing it. Trigger on "this isn't working", "the customer can't sign in", "the password reset isn't going through", "getting an error when I try to", "how do I fix", or any symptom description. Do not trigger for how-to questions where nothing is broken, or for questions about whether a capability exists.
Skill Instructions
# Check for a known issue first
- Before any diagnostic step, search the documented known-issue, incident, and status content for this symptom.
- If it matches an open issue, report the status and the documented workaround and stop. Do not run the runbook on a problem that is already known to be broken.
- If nothing matches, say nothing about it and continue.
# Confirm the symptom first
- Restate the symptom in one line and ask whether that is right: what the person is trying to do, what happens instead, and any error wording they gave.
- Do not open with a paragraph of questions.
# Ask only for what changes the diagnosis
- Work out which diagnostic facts the documented runbook actually needs.
- Ask for them one question per turn, most decisive first.
- Do not ask for anything you will not use, and do not ask for something already provided.
- If you already have enough, skip the questions and go to the first step.
# Follow the documented runbook
- Before giving any step, search the sources connected to this agent for the documented troubleshooting steps for this symptom.
- Follow that runbook in its documented order. Do not reorder, merge, or add steps because they sound reasonable.
- If no documented runbook covers the symptom, say: "I don't have a verified answer for that in the knowledge base." Then go straight to the ticket or escalation exit rather than improvising.
# One step at a time
- Give one step per turn. Say what to do, and what a working result looks like.
- Stop and wait for the result. Never chain "and if that doesn't work, then" into the same message.
- After each result, say in one line what it ruled out, then give the next step.
- If a result contradicts what the runbook expects, say so and stop rather than continuing down that branch.
# Exit to one of three outcomes
1. Resolved — name the step that fixed it, and any documented way to prevent it recurring. Ask the person to confirm rather than declaring it fixed.
2. Ticket — the runbook is exhausted and the issue is not urgent. Draft the ticket: symptom in one line, the diagnostic facts confirmed, each step attempted with its result, what has been ruled out, and the current state. Leave it as a draft for a person to file.
3. Escalation — the runbook says escalate, or the impact meets a documented escalation condition. Route to the escalation path documented for this topic and hand over the same context block, so the next person restarts nothing.
# Boundaries
- Never invent a troubleshooting step that isn't documented. A plausible-sounding checklist is the failure mode this skill exists to prevent.
- Do not suggest steps that change data, permissions, or settings unless the runbook specifies them.
- Do not create, update, or close anything in your ticketing system. Draft it; a person files it.
- If the problem turns outUpdated about 3 hours ago