CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, evidence-driven skill with concrete commands and real log examples covering every platform, held back by redundancy (key rules stated two or three times) and a monolithic single-file layout where the event-type reference and command catalogs would be better split into bundled reference files. The read-only investigation nature means the destructive-operation validation cap does not apply.

Suggestions

Consolidate repeated rules: state the grep_search prohibition and the large-file/read_file warning once each in 'Important Rules' and remove the duplicated callouts in 'Tooling Strategy' and 'General rules'.

Move the ~95-line Event Type Reference to references/event-types.md (linked one level deep from SKILL.md) and keep a compact name/purpose summary table inline so the main file stays an overview.

Trim the Windows section to the essential Select-String patterns plus one node -e example, and cut the Response Guidelines example table to the single most instructive case to reduce token load.

DimensionReasoningScore

Conciseness

Mostly efficient — the event schemas, tooling commands, and formatting rules are non-obvious, proprietary information Claude cannot already know — but the file repeats itself: the grep_search prohibition appears three times ("Do not use `grep_search`", the Tooling Strategy bold callout, and Important Rules), the large-file/never-read-entire-log warning appears twice, and the Node.js one-liners for Windows are verbose. This is noticeably below anchor 4's 'minor instances' bar, but well above anchor 2 since there is no concept-explanation padding.

3 / 5

Actionability

Fully executable throughout: copy-paste grep/jq/PowerShell commands per platform, real JSONL event examples with annotated key attrs, a concrete escalation command (`github.copilot.debug.collectDiagnostics`), documentation URLs, and a worked Good/Bad response example. Not score 4 because there are no meaningful gaps — specific commands cover the common cases on every OS.

5 / 5

Workflow Clarity

The five-step Investigation Workflow (identify files → triage → read slices → root cause → remediation) is clearly sequenced, with evidence-based checkpoints ("Never assume causality without evidence", "Base conclusions on evidence from logs. Do not guess.") and explicit fallback escalation (diagnostics command → wiki → file an issue). It falls short of anchor 5 because there is no explicit feedback loop back to triage when a hypothesis is not confirmed, and the multi-session comparison step is only implicit guidance.

4 / 5

Progressive Disclosure

The file has clear, well-labeled sections and no nested-reference problem, but it is a single ~270-line monolith with no bundle files at all: the Event Type Reference (~95 lines of examples) and the per-platform command catalogs are exactly the bulk detail that belongs in a one-level-deep references/ file, leaving SKILL.md as an overview with a compact summary. That 'content that should be separate is inline' pattern matches anchor 3; structure itself is good, so it is above anchor 2.

3 / 5

Total

15

/

20

Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete domain and data source, explicit 'Use when' triggers phrased in natural user language, and a distinct niche with minimal conflict risk. The only weakness is slightly thin action coverage (a single composite action) and a few missing synonyms such as 'debug' or 'troubleshoot'.

DimensionReasoningScore

Specificity

The description names the domain ("unexpected chat agent behavior"), a concrete method ("analyzing direct debug logs in JSONL files"), and enumerates distinct investigation scenarios (slow requests, tool/subagent usage, loading failures). It stops short of anchor 5 because it describes essentially one composite action — investigate/analyze — without covering remediation or reporting outcomes.

4 / 5

Completeness

It clearly answers both parts: the "what" ("Investigate unexpected chat agent behavior by analyzing direct debug logs in JSONL files") and an explicit "when" clause ("Use when users ask why..." with four concrete trigger phrases). This matches the anchor 5 example structure exactly; it is not score 4 because the "when" is already explicit and specific rather than improvable.

5 / 5

Trigger Term Quality

Natural user phrasings like "why something happened", "why a request was slow", and "why instructions/skills/agents did not load" directly match how users would phrase these requests, and "JSONL"/"debug logs" add technical synonyms. A few natural terms are missing (e.g. "debug", "troubleshoot", "error", "logs not showing"), keeping it just below the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — chat agent behavior diagnosis via JSONL debug logs — with triggers ("why tools or subagents were used or skipped", "why instructions/skills/agents did not load") that are unlikely to fire for unrelated skills. It is written in third person ("Investigate", not "I can"), so no voice penalty applies.

5 / 5

Total

18

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

posit-dev/positron

Path

extensions/copilot/assets/prompts/skills/troubleshoot/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.