troubleshoot
Skill0 starsChanged 57 days agoMITView on GitHub
Investigate unexpected behavior in the current Copilot agent session by analyzing its event log. Use when the user asks why something happened, why a request was slow, why a tool was or was not used, or why instructions/skills/agents did not load.
29 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- pantheon-org/tekhnetheir own version, first seen Nov 15, 2026
- Trixx4191/asrartheir own version, first seen Nov 15, 2026
- mystilleef/spae-frameworktheir own version, first seen Nov 13, 2026
- naman10parikh/pennytheir own version, first seen Nov 8, 2026
- synchronicity-labs/skillstheir own version, first seen Nov 8, 2026
- naman10parikh/wikimemtheir own version, first seen Nov 8, 2026
Used with
Projects with it also use ecosystem-reference, fractal-delegation and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
naman10parikhSkillecosystem-reference
Quick-access directory of Claude Code ecosystem repos, skills, plugins, MCPs, and patterns. Use when improving the harness.
Also in 5 projects that use this
naman10parikhSkillfractal-delegation
Also in 5 projects that use this
roronoazoroshao369Skillmemory-compression
Also in 5 projects that use this
KirchliveSkillskill-routing
Decides which of the installed skills a task needs and loads them before the work starts. This skill should be used at the beginning of any multi-step task — build, fix, refactor, migrate, review, plan, release, research, write, design, video — and again at every phase change, after context compaction, and when work moves into a different part of the codebase. Use it for requests like "let's build X", "fix this bug", "refactor Y", "plan the migration", "review this", and also when the user asks which skill applies, why a skill did not fire, or asks to check what is available.
Also in 5 projects that use this
sublimotionSkillagent-runtime
Launch and manage detached agent runs on EKS via the agent-runner CLI. Use when the user says "launch an agent run", "agent runtime", "agent-runner", "run this spec on the cluster", "check run status", "agent run logs", or "stop a run". Do NOT use for writing the agent-runner code itself (edit the sibling ../agent-runner repo), Terraform of the foundation (use terraform-automation), or GPU serving deployments (use infra-deployer).
Also in 5 projects that use this
- +5 more from naman10parikh
Other versions29 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- patterson-agents/skills★ 099% same
Wrote their own version · 28
- microsoft/vscode★ 195ksame name
- DeL-TaiseiOzaki/claude-code-orchestra★ 199same name
- serithemage/serverless-openclaw★ 196same name
- Azure-Samples/art-voice-agent-accelerator★ 74same name
- cafferychen777/ChatSpatial★ 45same name
- microsoft/Employee-Self-Service-Agent-Developer-Kit★ 31same name
- laaielichter/Reverseport★ 23same name
- google/ml-workload-debugging-wiki★ 20same name
- jamie8johnson/cqs★ 18same name
- pantheon-org/tekhne★ 10same name
18 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository32 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- act-on-feedbackSkill
- algorithmic-artSkill
- animateSkill
- canvas-designSkill
- coderSkill
- code-reviewSkill
- coderSkill
- commitSkill
- create-draft-prSkill
- create-prSkill
- criticSkill
- designerSkill
- design-taste-frontendSkill
- fix-ciSkill
- frontend-designSkill
- generalistSkill
- generate-run-commandsSkill
- mergeSkill
- ponytailSkill
- researcherSkill
- researcherSkill
- securitySkill
- shadcnSkill
- syncSkill
- sync-upstreamSkill
- theme-factorySkill
- toolsSkill
- ui-ux-pro-maxSkill
- update-prSkill
- update-skillsSkill
- web-design-engineerSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 3 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 23 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Use this skill for questions like:
- Very specific: line 124
every tool call with success/failure and duration (pair each tool.execution_start with its tool.execution_complete by toolCallId),
- Very specific: line 127
Use a streaming jq program (macOS/Linux) or a streaming Node readline pass (Windows) — the per-query examples below are the building blocks.
- Very specific: line 131
Check size first: ls -lh <logPath>
- Very specific: line 156
Use read_file only for small targeted ranges, never an entire log.
- Distinctive: line 162
Read only the relevant slices, then determine the most likely root cause (order contributing factors by impact) and give concrete next …
- Very specific: line 168
Abstraction: don't narrate your investigation or use internal terms (events.jsonl, tool.execution_start, parentId, "envelope").
- Very specific: line 177
Search via run_in_terminal.
- Distinctive: line 178
If no Copilot session log exists, say so and stop.
“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->Troubleshoot
Purpose
This skill investigates and explains unexpected agent behavior in the current Copilot agent session using its on-disk event log.
Use this skill for questions like:
- Why did this request take so long?
- Why was a tool called (or not called)?
- Why did an instruction/skill/agent file not load?
- Why did a tool call fail?
- Why did the model not follow expectations?
Base every conclusion on evidence from the event log. Do not guess.
Locating the Session Log
The skill runs inside the session's agent, so the log is on the same machine. It lives outside the workspace — read it via the terminal (run_in_terminal), never grep_search.
- If a
Session log:path is provided with this message, use it. It may point to a session other than the current one (via#session) and may be comma-separated paths — investigate all of them and compare. - Sticky reference: if no path is on the current message but an earlier turn in this conversation already established a target (a
Session log:path, or a#session:reference), keep analyzing that same session for the follow-up. Do not fall back to self-discovery here — the newest log is the current session, which is the wrong one. Switch only if the user references a new session. - Otherwise, self-discover it: pick the most recently modified
events.jsonlunder${XDG_STATE_HOME:-$HOME}/.copilot/session-state/<sessionId>/— this skill is appending to the current session's log, so it's reliably newest. HonorXDG_STATE_HOME, else$HOME. - If none exists there, this isn't a Copilot session — tell the user the skill supports Copilot sessions only, and stop.
Data Source — events.jsonl
Each line is a JSON object sharing one envelope:
{ "type": "...", "id": "...", "parentId": "...", "agentId": "...", "timestamp": "ISO-8601", "data": { } }type— the event kind (see below).id— unique event id.parentId— the chronologically preceding event, not a logical parent. It is a flat back-pointer over every event, not the user → turn → tool-call hierarchy. Do not treat it as a logical parent.agentId— present for sub-agent events; absent for the main agent and session-level events.timestamp— ISO-8601 time. Compute durations by differencing timestamps (e.g. a tool's start vs. its completion, a turn'sassistant.turn_startvs. theassistant.message).data— type-specific payload.
Event types (data.* fields)
session.start(once) —selectedModel,reasoningEffort.user.message—content;transformedContent(expanded prompt, when it differs).assistant.turn_start/assistant.turn_end—turnId; measure a turn's duration vs the followingassistant.message.assistant.message—model,outputTokens,content,reasoningText(thinking, when present),turnId,parentToolCallId(set ⇒ sub-agent turn spawned by that tool call).tool.execution_start—toolName,toolCallId,arguments,parentToolCallId(set ⇒ nested/sub-agent).tool.execution_complete—toolCallId(matches start),success,result. Pair with its start bytoolCallIdfor the full call + duration.session.shutdown(once, at end) —modelMetrics[*].usage,totalNanoAiu. Absent mid-session.- Other (
hook.*,permission.*,system.message) — inspectdataas needed.
Reconstructing the flow
Iterate records in order and rebuild the logical tree from context:
session.startis the root.- a
user.messagebegins a turn. - an
assistant.messageanswers the currentuser.message— unless it hasdata.parentToolCallId, in which case it belongs to the sub-agent spawned by that tool call. - a
tool.execution_startbelongs to the currentassistant.message— unless it hasdata.parentToolCallId, in which case it is nested under that parent tool call. - pair each
tool.execution_startwith itstool.execution_completebytoolCallId.
Secondary Source — Agent Host Wire Log (protocol communication)
events.jsonl is the primary source and answers almost every question on its own. A separate log captures the transport/protocol between VS Code and the agent host process — the JSON-RPC-style frames that drive sessions.
Use the wire log only when the symptom points at the agent host / transport itself, not the model or a tool. Reach for it when:
- the agent host won't start, or the session never begins;
- requests hang or time out, or the agent appears stuck "connecting" / unresponsive;
createSession/subscribefails, or expected updates/notifications never arrive;- you see RPC / protocol / connection errors.
Do not open it for ordinary "why did the model/tool do X" questions — events.jsonl already answers those. If events.jsonl fully explains the behavior, stop there and don't read the wire log.
It is written by VS Code on the client machine, so it is only reachable for a local agent host (VS Code and the agent on the same machine). For a remote agent host it lives on the client, not the host this skill runs on — skip it there.
Location
<VS Code user-data dir>/logs/<session-timestamp>/ahp/ahp-<timestamp>-<connectionId>.jsonlThe VS Code user-data dir depends on the build:
- Windows:
%APPDATA%\Code(Insiders:Code - Insiders; OSS/dev may useCode - OSSor a custom--user-data-dir) - macOS:
~/Library/Application Support/Code - Linux:
~/.config/Code
A new logs/<timestamp>/ folder is created per VS Code session — pick the most recently modified ahp/ahp-*.jsonl.
Named by connection id, not session id — one log multiplexes all sessions on that connection (no per-session file). Long connections rotate into ahp-….1.jsonl, .2.jsonl, … (max 5); the active one is the most recently modified (the locate commands pick it). Read the newest log for connection-level health; to isolate one session, filter by its id (the session-state/<sessionId>/ folder name, which appears in frames' params/result).
If no ahp/ folder exists, the wire log is disabled (it is off by default). Tell the user to set "chat.agentHost.ahpJsonlLoggingEnabled": true, restart VS Code, reproduce the issue, then re-run.
Format
Each line is a JSON-RPC frame plus an _ahpLog envelope:
{ "jsonrpc": "2.0", "id": 12, "method": "createSession", "params": {}, "_ahpLog": { "ts": "ISO-8601", "dir": "c2s", "connectionId": "…", "transport": "local" } }_ahpLog.dir— direction:c2s= VS Code → host (requests/notifications),s2c= host → VS Code (results/errors/actions/notifications)._ahpLog.transport—local/websocket/ssh/wsl.- Requests/notifications carry
method+params; responses carryresultorerror— pair a response to its request byid. _ahpLog.truncated: truemarks frames whose large payloads were elided.
Triage: look for error frames, requests (c2s with an id) that have no matching s2c response (hangs/timeouts), or a missing s2c after createSession / subscribe. Apply the same streaming / jq / node rules as for events.jsonl.
Locating it (terminal)
- macOS/Linux:
ls -t ~/Library/Application\ Support/Code*/logs/*/ahp/ahp-*.jsonl ~/.config/Code*/logs/*/ahp/ahp-*.jsonl 2>/dev/null | head -n 1 - Windows (PowerShell):
Get-ChildItem "$env:APPDATA\Code*\logs\*\ahp\ahp-*.jsonl" -ErrorAction SilentlyContinue | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Tooling Strategy (important)
The event log is outside the workspace, so grep_search cannot read it. Use run_in_terminal.
Do a single triage pass first (important for efficiency)
Each terminal command is a separate round-trip, so don't run one command per question. Do one streaming pass (constant memory — events.jsonl can be hundreds of MB, so never load it whole) that prints, in a single read:
- the event counts by type,
- every tool call with success/failure and duration (pair each
tool.execution_startwith itstool.execution_completebytoolCallId), - the user messages.
Use a streaming jq program (macOS/Linux) or a streaming Node readline pass (Windows) — the per-query examples below are the building blocks. Then run targeted follow-ups only to drill in.
macOS / Linux / WSL / Git Bash (grep / jq)
- Locate the newest log:
ls -t "${XDG_STATE_HOME:-$HOME}"/.copilot/session-state/*/events.jsonl | head -n 1 - Check size first:
ls -lh <logPath> - Errors:
grep '"success":false' <logPath>(tool failures) andgrep '"type":"tool.execution_complete"' <logPath> - Count events by type (streaming):
jq -nr 'reduce inputs as $i ({}; .[$i.type] += 1) | to_entries | sort_by(-.value)[] | "\(.value) \(.key)"' <logPath> - Tool calls:
jq -c 'select(.type=="tool.execution_start") | {tool:.data.toolName, id:.data.toolCallId}' <logPath> - User messages:
jq -c 'select(.type=="user.message") | .data.content' <logPath> - Assistant turns:
jq -c 'select(.type=="assistant.message") | {model:.data.model, out:.data.outputTokens}' <logPath>
Windows (PowerShell + Node.js)
Do not parse the log with PowerShell JSON. Get-Content … | ForEach-Object { ConvertFrom-Json } (or any per-line ConvertFrom-Json) deserializes one object at a time and is slow even on small logs. Use Select-String for plain-text matches and a streaming node pass for anything that needs JSON. Use jq instead if it is available.
- Locate the newest log:
$stateHome = if ($env:XDG_STATE_HOME) { $env:XDG_STATE_HOME } else { $HOME } Get-ChildItem (Join-Path $stateHome '.copilot\session-state\*\events.jsonl') | Sort-Object LastWriteTime -Descending | Select-Object -First 1 - Check size first:
(Get-Item <logPath>).Length - Plain-text matches (fast, streaming, no parsing):
Select-String '"success":false' <logPath> - JSON queries — a streaming
nodepass (constant memory, safe for hundreds-of-MB logs; pass the log path as an argument so it stays quote-safe). Use this shape and change only the per-lineif (…)to select what you need (tool failures, tool calls, assistant turns, …):node -e "const rl=require('readline').createInterface({input:require('fs').createReadStream(process.argv[1])});rl.on('line',l=>{if(!l)return;let x;try{x=JSON.parse(l)}catch{return}if(x.type==='tool.execution_complete'&&x.data.success===false)console.log(x.data.toolCallId,JSON.stringify(x.data.result))})" "<logPath>"For aggregates (e.g. counts by type), accumulate into an object as you go and print it onrl.on('close', …). - For a very large log, narrow with
Select-Stringfirst to find the line, then read that small slice withread_file.
General rules
- One streaming pass, not many. Each command is a round-trip; prefer the single triage pass, then targeted follow-ups. Never load a whole (hundreds-of-MB) log into memory (
readFileSync/Get-Content) — stream (jq/ the readline pass) or narrow withgrep/Select-Stringfirst. Check size first if unsure (ls -lh/(Get-Item).Length). - Never deserialize JSON line-by-line in the shell (PowerShell
ConvertFrom-Jsonin a loop) — slow. Use onejqfilter or onenodepass. - Use
read_fileonly for small targeted ranges, never an entire log.
Investigation Workflow
- Locate
events.jsonland run the single triage pass. - Match the symptom: errors →
success:false; latency → gaps betweenassistant.turn_startand itsassistant.message, or a tool's start↔complete; tool / model / input → the relevant event type; agent-host / transport failure (local) → also the Wire Log. - Read only the relevant slices, then determine the most likely root cause (order contributing factors by impact) and give concrete next steps.
Response Guidelines
Cover what happened and why (root cause), key evidence (paraphrased — quote only a telling detail like an error message, never raw dumps), and how to fix it. A short combined explanation is fine; add structure (headers, bullets, tables) only for complex, multi-factor issues. Keep paragraphs short.
Abstraction: don't narrate your investigation or use internal terms (events.jsonl, tool.execution_start, parentId, "envelope"). Refer to "the session log" abstractly. Focus on what happened and why, not how you found it.
Example — instead of "I read events.jsonl and saw a tool.execution_complete with success:false…", say:
The "testing" skill was found but not loaded because the folder name and the name in the skill file differ (
testingvstesting2). Fix: make them match (rename the folder or change the name), then start a new session.
Important Rules
- Base every claim on log evidence — never assume causality.
- Search via
run_in_terminal; nevergrep_search, and neverread_filea whole (possibly huge) log — narrow first, then read small ranges. - If no Copilot session log exists, say so and stop.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

