skill-doctor

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

Quality

71%

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

Quality

Content

85%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 body is highly actionable with complete executable scripts, a clearly sequenced five-step workflow, and explicit validation/feedback loops for destructive remediation. Its main weakness is progressive disclosure: a large amount of reference material is inlined in a single file with no split into bundled reference documents.

Suggestions

Move the bulk reference sections (Hook Profile, Intensity Profile, Project Tier Hint, Remote Session Checks, Runtime Context) into a bundled reference file (e.g. references/PROFILES.md) and link to it from SKILL.md so the main file stays a concise overview.

Tighten explanatory prose such as the "Why It Matters" and profile narrative paragraphs to lift conciseness toward a 5.

Provide a concrete login command for the "Auth expired" remediation rather than only "Offer to run the login command for the expired provider."

Dimension	Reasoning	Score
Conciseness	The body is dense and actionable — copy-paste bash resolver, command tables, AskUserQuestion code blocks — with little padding of concepts Claude already knows; minor over-explanation remains in reference prose like "Without a RUNTIME.md, orchestration prompts lack project-specific details — leading to generic advice...", so it is not a 5.	4 / 5
Actionability	Provides fully executable, copy-paste-ready guidance throughout — the complete Step 1 resolver bash script, per-category `bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor <category>` lines, `install-deps.sh check/install`, and concrete AskUserQuestion remediation blocks; not downgraded because the few high-level lines ("Offer to run the login command for the expired provider") are outweighed by complete scripts.	5 / 5
Workflow Clarity	Steps 1–5 are explicitly sequenced and the destructive remediation in Step 5 has real validation feedback loops — "Configuration repairs must use a validated sibling temporary file and atomic rename; if any step fails, keep the original" and "rerun only the affected category first, then offer a full scan" — so the destructive-op cap does not apply.	5 / 5
Progressive Disclosure	Sections are clearly headed and navigable, but the skill is a ~400-line monolith with no bundle files (no references/, scripts/, or assets/ exist) and bulk reference material (Hook Profile, Intensity Profile, Project Tier Hint, Remote Session Checks, Runtime Context) is inlined rather than split into separate files; not a 4 because no external navigation is signaled.	3 / 5
	Total	17 / 20 Passed

Description

58%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 cleanly states what the skill does and names several concrete check domains, but it omits any explicit "when to use" trigger guidance and relies on jargon-heavy terms rather than the natural phrases users would say. Adding a "Use when..." clause with user-facing trigger terms would lift completeness and trigger_term_quality.

Suggestions

Append a "Use when..." clause to the description (e.g. "Use when the user asks to run a doctor/health check, or something in their Octopus setup isn't working") so completeness is not capped at 3.

Surface natural user phrasings — "health check", "is everything working", "what's wrong with my setup" — in the description itself rather than only in the trigger field, to improve trigger_term_quality.

Drop or bound the trailing "and more" to reduce overlap risk and make the niche fully distinct.

Dimension	Reasoning	Score
Specificity	Lists several concrete check targets — "providers, auth, config, hooks, scheduler" — under a named domain ("Environment diagnostics"), matching the anchor for several specific actions with minor coverage gaps introduced by "and more"; not a 5 because the single repeated verb "check" is generic rather than enumerating distinct actions.	4 / 5
Completeness	Has a clear "what" ("Environment diagnostics — check providers, auth, config, hooks, scheduler") but no "Use when..." clause or explicit "when" guidance in the description, so per the missing-trigger-clause cap it cannot exceed 3; not a 4 because the "when" is entirely absent rather than weakly implied.	3 / 5
Trigger Term Quality	Contains relevant terms ("diagnostics", "check providers", "check auth", "check hooks") but these lean toward domain jargon and miss the natural phrasings a user would actually say (e.g. "is everything working", "health check"), which live in the trigger field rather than the description; not a 4 because common variations/synonyms are absent from the description itself.	3 / 5
Distinctiveness Conflict Risk	The "Environment diagnostics" niche with concrete check areas is mostly distinct from sibling skills (setup/status/debug are explicitly separated elsewhere), with only minor overlap risk from the broad "and more"; not a 5 because that trailing generality keeps it from a fully bounded niche.	4 / 5
	Total	14 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	14 / 16 Passed

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-doctor/SKILL.md
Commit: 1bee725

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