CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

investigate

Systematic root-cause debugging: find the cause before writing any fix

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./examples/skills/investigate/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

81%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.

The content is a strong, highly actionable debugging workflow with explicit sequencing, validation checkpoints, and feedback loops throughout. Its weaknesses are minor: a little redundancy between phases and the rules section, a non-functional grep glob, and missed opportunities to move reference-style tables/templates into separate files.

Suggestions

Fix the grep include pattern: quoted brace globs like '--include="*.{ts,js,py,rb,go}"' are not expanded by grep; use multiple --include flags instead.

Deduplicate the 'Important rules' section against the phase instructions (e.g. the verify-before-fix and 3-strike rules appear twice) to trim tokens.

Consider moving the bug-pattern table and the output/escalation format templates into a one-level-deep reference file, keeping SKILL.md as a leaner overview.

DimensionReasoningScore

Conciseness

The body is largely lean and assumes Claude's competence (no basic-concept explanations), with genuinely useful lookup material like the compact bug-pattern table. Minor instances of over-explanation could be trimmed: the motivational rationale ('Fixing symptoms creates whack-a-mole debugging...') and the 'Important rules' section restate guidance already given in the phases.

4 / 5

Actionability

Guidance is mostly executable: concrete grep/git commands, runnable test invocations, and copy-paste JS/Python diagnostic snippets covering common cases. Minor gaps remain, such as placeholder-laden commands and the '--include="*.{ts,js,py,rb,go}"' glob, which grep does not brace-expand when quoted, so that command will not match as written.

4 / 5

Workflow Clarity

The 7 phases are clearly sequenced with explicit validation checkpoints: reproduce before fixing, hypothesis confirmation via debug output, a feedback loop back to Phase 2 when a hypothesis fails, a 3-strike escalation decision point, a regression test that must fail without the fix, and a blast-radius check. This matches the top anchor's 'explicit validation steps; feedback loops for error recovery' standard, and the destructive/batch cap does not apply since verification is pervasive.

5 / 5

Progressive Disclosure

The single file is well organized with clear section headers, an output-format template, and no buried or nested references, and no bundle files exist to misorganize. It falls short of the top anchor because at ~230 lines some self-contained material (the bug-pattern table, output/escalation format templates) could be split into one-level-deep reference files to keep the SKILL.md overview leaner.

4 / 5

Total

17

/

20

Passed

Description

53%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.

The description is concise and states a clear, distinct capability, but it tells only half the story. It lacks any 'Use when...' trigger guidance and natural trigger terms users would say (bug, error, failing, broken), limiting both completeness and keyword coverage.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when the user reports a bug, error, failing test, or regression, or asks why something is broken.'

Include natural trigger terms and synonyms users actually say: 'bug', 'error', 'failing', 'broken', 'regression', 'investigate'.

Expand the capability list beyond one action, e.g. 'Collects symptoms, traces the code path, checks recent changes, tests hypotheses, then writes a minimal verified fix with a regression test.'

DimensionReasoningScore

Specificity

The description names the domain ("root-cause debugging") and a single concrete action ("find the cause before writing any fix"), which matches the anchor for 1-2 concrete actions without comprehensive coverage. It does not list several specific actions, so it falls below the level-4 anchor.

3 / 5

Completeness

The 'what' is clear (systematic root-cause debugging before fixing), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. The 'when' is at best weakly implied.

3 / 5

Trigger Term Quality

"debugging", "root-cause", and "fix" are natural terms a user might say, but common variations like "bug", "error", "failing", "broken", or "investigate" are missing, matching the 'some relevant keywords but missing common variations' anchor. Coverage is short of the 'good keyword coverage; a few natural terms missing' level.

3 / 5

Distinctiveness Conflict Risk

The investigation-before-fix framing carves out a mostly distinct niche with low conflict risk, though it could overlap with closely related skills like code review, general bug-fixing, or QA skills. It is more distinct than the 'somewhat specific but could still overlap' anchor but does not present the clear niche with explicit distinct triggers of level 5.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

FlorianBruniaux/claude-code-ultimate-guide

Path

examples/skills/investigate/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.