Agent skill · data analytics · microsoft
troubleshoot
Investigate unexpected chat agent behavior by analyzing direct debug logs in JSONL files. Use when users ask why something happened, why a request was slow, why tools or subagents were used or skipped, or why instructions/skills/agents did not load.
Why this skill is useful
Provides specific patterns for analyzing JSONL debug logs that the AI wouldn't reliably generate on its own.
What it needs
About 9k tokens when loaded. Last updated 2026-08-07. 188,455 stars on the source repository.
What this skill does
Troubleshoot Purpose This skill investigates and explains unexpected chat agent behavior using direct log files. Use this skill for questions like: Why did this request take so long? Why was a tool or subagent called? Why did instruction/skill/agent files not load? Why was a tool call blocked or failed? Why did the model not follow expectations? Base conclusions on evidence from logs. Do not guess. Data Source Target session log directory/directories for analysis: {{VSCODETARGETSESSIONLOG}} Use direct debug log files written by Copilot Chat: Always read main.jsonl first — it has the full conversation flow. Child files only appear when those operations occurred. main.jsonl contains childsessionref entries that link to each child file by name. Title, categorization, and summarize files are UI housekeeping and rarely relevant to troubleshooting. When investigating model availability or selection issues, read models.json — it contains the full list of models (with capabilities, billing, and limits) that were available when the session started. When investigating what the model was told (system prompt, instructions), read the systemprompt.json file referenced by a systempromptref entry in main.jsonl. The file contains the full untruncated system prompt as { "content": "..." }. When investigating which tools were available, read the tools.json file similarly. If the model changed mid-session, multiple numbered files exist — each llmrequest entry has a systemPromptFile attr indicating which file was active for that request. Each line is a JSON object. Common fields: ts (epoch ms), dur (duration ms), sid (session ID), type, name, spanId, parentSpanId, status (ok error), attrs (type-specific details). Event Type Reference with Examples discovery — customization file loading (instructions, skills, agents, hooks) Key attrs: details (human-readable summary with folder paths, loaded items, skip reasons), category (always "discovery"), source ("core"). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills microsoft/troubleshoot