skill-doctor

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

Quality

70%

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 ./skills/skill-doctor/SKILL.md

Quality

Content

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

This is a highly actionable, well-sequenced diagnostic skill: every command is executable, remediation is gated behind explicit authorization with dry-run previews and post-repair verification loops. Its weaknesses are redundancy (duplicated confirmation language and OCTO_PROFILE explanations) and the absence of any progressive disclosure — everything is inlined in one long file with one dangling reference.

Suggestions

Move the legacy intensity profile, context profile tables, remote-session checks, and tier hints into a references/profiles.md and reference it from a short section — this addresses the inlined reference material that caps progressive_disclosure.

Fix or remove the broken 'skills/blocks/codex-host-adapter.md' reference, since it currently points to a file that does not exist in the bundle.

Deduplicate the repeated 'cache cleanup, stale PID cleanup, login flows, package installation, and plugin updates require explicit confirmation' sentence in Step 5 and merge the overlapping OCTO_PROFILE explanations from 'Context and intensity profiles' and 'Legacy intensity profile' into one place.

Dimension	Reasoning	Score
Conciseness	The body is mostly dense, high-value operational content (resolver, commands, contracts, tables), but the confirmation sentence about cache/PID/login/package/plugin actions appears twice nearly verbatim in Step 5, and OCTO_PROFILE's separation from the context profiles is explained redundantly in both 'Context and intensity profiles' and 'Legacy intensity profile'. It is not a 4 because these repeated passages are clearly trimmable, and not a 2 because the bulk is genuinely necessary, not padded explanation.	3 / 5
Actionability	Guidance is fully executable: a complete plugin-root resolver script, exact per-category doctor commands, the install-deps check/install invocations, the exact JSON output contract, copy-paste AskUserQuestion payloads, and issue-to-fix tables. Not below 5 because nothing is pseudocode or left to inference.	5 / 5
Workflow Clarity	Steps 1-5 are clearly sequenced with explicit validation checkpoints and feedback loops: the repair path requires a --dry-run preview before --apply, config repairs use a validated temp file with atomic rename and keep-original-on-failure, and after repair only the affected category is rerun first before offering a full scan. Exit-code semantics for fail/warn/usage errors are specified so errors are not misretried.	5 / 5
Progressive Disclosure	There are no bundle files at all, so all ~435 lines live inline in SKILL.md, and the single cross-reference to 'skills/blocks/codex-host-adapter.md' points to a nonexistent path. Section headers are clear, but the legacy intensity tables, context-profile detail, and remote-session checks clearly belong in a separate reference file, matching 'some structure but content that should be separate is inline'. It is not a 4 because the one reference present is broken and the split-out opportunity is substantial, and not a 2 because headers and a Quick Reference table make navigation genuinely possible.	3 / 5
	Total	16 / 20 Passed

Description

62%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 communicates a clear diagnostic purpose with five concrete check areas and largely natural trigger keywords, but it omits any 'use when' guidance and never identifies which environment or plugin it diagnoses, limiting completeness and distinctiveness. It sits solidly above a generic one-liner yet below the rubric's exemplar descriptions.

Suggestions

Add an explicit trigger clause, e.g. 'Use when something isn't working and you're not sure why, after installing or updating the plugin, or before a demo or important run' — this directly addresses the completeness cap.

Name the tool or environment being diagnosed (e.g. 'Claude Octopus environment diagnostics') so the description cannot collide with generic setup, status, or debug skills.

Add one or two natural troubleshooting synonyms users actually say ('something is broken', 'health check', 'why isn't it working') to strengthen trigger_term_quality, and drop the vague 'and more' in favor of one more concrete area.

Dimension	Reasoning	Score
Specificity	The description names the domain and five concrete check targets ("providers, auth, config, hooks, scheduler"), matching 'lists several specific actions; minor gaps'. It falls short of a 5 because 'and more' is open-ended and 'check' is the only action verb, and is above 3 because it enumerates five specific areas rather than 1-2.	4 / 5
Completeness	The 'what' is clear (environment diagnostics checking providers, auth, config, hooks, scheduler), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric guideline. It is not a 2 because the what half is concrete, not vague.	3 / 5
Trigger Term Quality	Terms like 'diagnostics', 'auth', 'config', 'hooks', and 'scheduler' are natural phrases users would say when they need this skill, giving good keyword coverage. Common troubleshooting variations ('not working', 'broken', 'health check', 'troubleshoot') are missing, so it does not reach the comprehensive synonym coverage of a 5.	4 / 5
Distinctiveness Conflict Risk	It is somewhat specific (environment diagnostics for providers/auth/hooks/scheduler) but does not name the tool it diagnoses, and 'config' and 'and more' create real overlap risk with sibling setup/status/debug skills in the same plugin. Not a 4 because the missing tool identity and the open-ended tail genuinely blur the boundary with those closely related skills.	3 / 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
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: nyldn/claude-octopus
Path: skills/skill-doctor/SKILL.md
Commit: 0093dab

Reviewed: 5 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.