skill-debug

Debug issues methodically — use when stuck on errors, test failures, or unexpected behavior

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-debug/SKILL.md

Quality

Content

62%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 skill defines a clear, well-sequenced debugging workflow with strong validation checkpoints and feedback loops, and provides concrete executable commands. It is held back by noticeable verbosity from repeated 'don't skip the process' sections and a lack of progressive disclosure for its length.

Suggestions

Collapse the redundant emphasis sections ('Iron Law', 'Red Flags', 'Common Rationalizations', 'Anti-rationalization rules', 'Strategy Rotation') into a single concise 'Discipline' block to cut token cost.

Move the Claude Octopus integration, multi-agent debugging, and WTF-score configuration details into reference files and link to them one level deep from SKILL.md.

Trim theatrical emphasis ('MANDATORY COMPLIANCE', 'PROHIBITED', HARD-GATE) since the workflow itself already enforces the process.

Dimension	Reasoning	Score
Conciseness	At ~370 lines the body is noticeably verbose with several redundant sections — 'Iron Law', 'MANDATORY COMPLIANCE', 'Red Flags', 'Common Rationalizations', 'Anti-rationalization rules', and 'Strategy Rotation' all restate the same 'don't guess, follow the process' message, plus theatrical emphasis ('PROHIBITED', HARD-GATE).	2 / 5
Actionability	Concrete executable commands appear throughout — git diff/log, boundary instrumentation echoes, the freeze-mode bash script, and orchestrate.sh invocations — with decision tables for hypothesis results and the 3-strike rule; minor gaps remain in some steps being high-level directives.	4 / 5
Workflow Clarity	The four phases are explicitly sequenced with arrows and each has validation checkpoints (failing test before fixing, verify-fix, hypothesis result table, 3-strike rule) plus feedback loops returning to Phase 1 or 3 on failure.	5 / 5
Progressive Disclosure	The body has clear section headers but is monolithic at ~370 lines with no bundle files; content that could live in separate references (Octopus integration, multi-agent debugging, platform debugging, WTF-score detail) is inlined and no one-level-deep references are signaled.	3 / 5
	Total	14 / 20 Passed

Description

65%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 clearly states both what the skill does and when to use it, with a solid explicit trigger clause and natural keywords. Its main weakness is the generic 'what' — it names the debugging domain without listing concrete actions.

Suggestions

Replace the generic verb with concrete debugging actions, e.g. 'Reproduce, trace root causes, and fix bugs methodically'.

Add a couple of natural synonyms users say, such as 'bug', 'broken', or 'troubleshoot', to round out trigger coverage.

Keep the explicit 'use when' clause but pair it with a fuller capability list to lift specificity toward the top anchor.

Dimension	Reasoning	Score
Specificity	The description states 'Debug issues methodically' which names the domain but the action is minimal and generic; it lists issue types (errors, test failures, unexpected behavior) rather than concrete debugging actions like reproduce, trace, or hypothesize.	2 / 5
Completeness	Both 'what' (debug issues methodically) and 'when' (use when stuck on errors, test failures, or unexpected behavior) are present with an explicit trigger clause; the 'what' could be more comprehensive, keeping it just below a 5.	4 / 5
Trigger Term Quality	The phrase 'use when stuck on errors, test failures, or unexpected behavior' provides good natural keyword coverage users would actually say, though common variations like 'bug', 'broken', or 'troubleshoot' are missing.	4 / 5
Distinctiveness Conflict Risk	Debugging is a mostly distinct niche with concrete triggers; 'unexpected behavior' is broad enough to create minor overlap risk with related engineering skills.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-debug/SKILL.md
Commit: bc76e7c

Reviewed: about 2 hours ago

Table of Contents

Discovery Implementation Validation

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.