skill-doctor

Environment diagnostics — check providers, auth, config, hooks, scheduler, and more

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

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

Quality

Content

77%

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

The content is highly actionable with executable commands and a clearly sequenced, checkpointed diagnostic-to-remediation workflow. Its main weakness is progressive disclosure: everything lives inline in one ~325-line file with no bundle files to offload the reference-heavy profile/section material.

Suggestions

Move the Hook Profile, Intensity Profile, Project Tier, Remote Session, and Runtime Context reference material into a references/ file (e.g. references/profiles.md) and link to it one level deep from SKILL.md.

Tighten legacy-compatibility notes (e.g. OCTO_HOOK_PROFILE mapping) into a short 'deprecated' line to reduce token overhead.

After Step 5 remediation, add an explicit 're-run diagnostics to confirm the fix' checkpoint to make the feedback loop fully closed.

Dimension	Reasoning	Score
Conciseness	The body is mostly operational and avoids explaining concepts Claude already knows, but at ~325 lines it carries inline reference material (multiple profile tables, legacy-compat notes, remote/runtime sections) that could be tightened or split out, matching the 'mostly efficient but could be tightened' anchor.	2 / 3
Actionability	It provides complete, copy-paste-ready executable bash (the plugin-root resolver) and full AskUserQuestion code blocks with specific install commands, matching the 'fully executable code/commands; copy-paste ready' anchor.	3 / 3
Workflow Clarity	Steps 1–5 are explicitly sequenced, the check-categories and common-issues tables act as checklists, and Step 5 ('MANDATORY for fixable issues') with batched remediation provides a clear diagnose→fix feedback loop, matching the score-3 anchor.	3 / 3
Progressive Disclosure	No bundle files exist in references/scripts/assets, and the skill is a single well-sectioned file; however content that could live separately (Hook/Intensity/Tier profiles, Remote and Runtime Context reference) is all inline with no one-level-deep references, fitting 'content that should be separate is inline'.	2 / 3
	Total	10 / 12 Passed

Description

50%

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 clear and names a real domain plus specific check categories, but it relies on a single action verb and omits any explicit 'when to use' trigger guidance. It is solid but generic enough to risk overlap with sibling diagnostic skills.

Suggestions

Add an explicit trigger clause, e.g. 'Use when something isn't working and you're unsure why, or to verify providers/auth/hooks/scheduler are correctly configured.'

Vary the action verbs beyond 'check' to convey distinct outcomes, e.g. 'diagnoses provider/auth/config issues, detects broken hooks and stale state, recommends fixes'.

Add natural-language variants users would say ('troubleshoot', 'doctor', 'diagnose environment') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('Environment diagnostics') and lists several concrete check areas ('providers, auth, config, hooks, scheduler, and more'), but the only action verb is the single repeated 'check' rather than multiple distinct concrete actions like the score-3 anchor.	2 / 3
Completeness	It answers 'what does this do' but has no 'Use when...' clause or equivalent explicit trigger guidance for when to invoke it, which caps completeness at 2 per the judging guidelines.	2 / 3
Trigger Term Quality	'Environment diagnostics' and 'check providers/auth/config/hooks/scheduler' are terms a user might naturally say, but common variations like 'diagnose', 'troubleshoot', 'doctor', or 'fix environment issues' are missing.	2 / 3
Distinctiveness Conflict Risk	'Environment diagnostics' with listed categories is a recognizable niche, but it could still overlap with adjacent skills like /octo:debug or /octo:status mentioned in the body, so it is not fully conflict-free.	2 / 3
	Total	8 / 12 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
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-doctor/SKILL.md
Commit: 9f39f0c

Reviewed: 2 days 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.