CtrlK
BlogDocsLog inGet started
Tessl Logo

skill-doctor

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

58

Quality

68%

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 ./.claude/skills/skill-doctor/SKILL.md
SKILL.md
Quality
Evals
Security

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.

The skill is highly actionable with an exemplary validated workflow — executable commands everywhere, dry-run/authorization checkpoints, and documented exit-code semantics. Its weaknesses are a monolithic single-file structure with no progressive disclosure offloading (the inlined resolver script and remediation dialogs belong in scripts/ and references/) and localized verbosity, including a duplicated remediation-confirmation sentence.

Suggestions

Move the 40-line plugin-root resolver into scripts/resolve-root.sh and reference it with a one-line invocation, eliminating the repeated 'reuse the resolver from Step 1' instructions and the inlined boilerplate.

Move the AskUserQuestion remediation dialogs (RTK install, RTK hook, missing providers) into a references/remediation.md file, keeping only the decision rules (when to offer, batching with multiSelect, dry-run before apply) in SKILL.md.

Remove the duplicated sentence 'Cache cleanup, stale PID cleanup, login flows, package installation, and plugin updates... require explicit confirmation' (appears in both the Step 5 preamble and the post-repair paragraph), keeping it in one place.

DimensionReasoningScore

Conciseness

The body is mostly dense with skill-specific facts (exit-code contracts, repair rules, JSON schema), but it is noticeably padded in places: 'Cache cleanup, stale PID cleanup, login flows, package installation, and plugin updates... require explicit confirmation' appears nearly verbatim twice (Steps 1's remediation preamble and Step 5), and the 40-line resolver is inlined where a one-line reference to a script would do. Fits 'mostly efficient but could be tightened', not level 2 (no widespread explanation of concepts Claude already knows) nor level 4 (the duplication and inlined boilerplate are more than minor).

3 / 5

Actionability

Everything is copy-paste executable: a complete resolver bash script, exact per-category doctor commands, the JSON outer contract, ready-to-use AskUserQuestion dialogs, and a concrete issue/fix table. This matches 'fully executable; copy-paste ready code or commands; specific examples cover the common cases'; level 4 would leave gaps in the common cases, and there are none.

5 / 5

Workflow Clarity

Five clearly sequenced steps with explicit validation checkpoints and feedback loops: 'repair --dry-run' shown before 'repair --apply', explicit authorization required, 'After repair, rerun only the affected category first, then offer a full scan', and documented exit-code semantics with 'do not retry them as full scans' for usage errors. The destructive/batch cap does not apply because validation is present, so this matches the top anchor rather than the level-4 anchor (which tolerates minor validation gaps).

5 / 5

Progressive Disclosure

There are no bundle files at all — the SKILL.md is a monolithic ~430-line file with good headers and tables, but content that clearly belongs in separate files is inlined: the 40-line resolver script (referenced repeatedly as 'reuse the resolver') belongs in scripts/, and the AskUserQuestion remediation dialogs and legacy-profile summary tables belong in references/. This matches 'some structure but... content that should be separate is inline'; not level 2 (structure is present and navigation is possible) and not level 4 (nothing is split out at all).

3 / 5

Total

16

/

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 is specific and distinct, naming six concrete diagnostic targets, but it omits any 'when to use' guidance — the trigger phrases live in a separate trigger: frontmatter field — and its keyword coverage misses the natural variations users would say ('health check', 'why isn't it working', 'run doctor'). This is a mid-range description: clear on capability, weak on activation.

Suggestions

Append an explicit trigger clause to the description itself, e.g.: 'Use when the user says doctor, diagnostics, health check, is everything working, or why isn't octopus working' — this lifts completeness past the cap of 3.

Include the natural synonyms already present in the trigger: field (health check, environment check, why isn't it working) so the description alone carries the keywords users actually say.

Add a distinguishing cue (e.g., 'Claude Octopus plugin diagnostics') to reduce overlap with Claude Code's native /doctor and generic troubleshooting skills.

DimensionReasoningScore

Specificity

'check providers, auth, config, hooks, scheduler' names several concrete check targets, matching 'lists several specific actions; minor gaps in coverage'. It falls short of the level-5 anchor because 'and more' hedges instead of enumerating, and 'Environment diagnostics' names the domain rather than concrete diagnostic actions (e.g., identifying misconfigured providers); it is above level 3, which expects only 1-2 concrete actions.

4 / 5

Completeness

The 'what' is clear (environment diagnostics across named subsystems), but the description contains no 'Use when...' clause or equivalent explicit trigger guidance — that guidance lives in the separate trigger: field, which per the judging guidelines caps completeness at 3. It is not level 4 because the 'when' is entirely absent from the description itself, and not level 2 because the 'what' is specific rather than vague.

3 / 5

Trigger Term Quality

Relevant keywords are present ('Environment diagnostics', 'check providers', 'check auth', 'check hooks'), but common natural phrasings users would actually say — 'health check', 'is everything working', 'why isn't it working', 'run doctor' — exist only in the separate trigger: frontmatter field, not in the description. This matches 'some relevant keywords but missing common variations or synonyms'; it is above level 2 (keywords are domain-specific, not generic) but below level 4's 'good keyword coverage'.

3 / 5

Distinctiveness Conflict Risk

The named subsystems (providers, auth, config, hooks, scheduler) give it a clear niche among plugin-ecosystem skills with distinct triggers, but 'Environment diagnostics' broadly overlaps with Claude Code's native /doctor command and general troubleshooting skills, keeping it at 'mostly distinct; minor overlap risk' rather than the level-5 minimal-conflict anchor.

4 / 5

Total

14

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

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