skill_doctor

skill_doctor

<skill_doctor_skill>

<when_to_activate> Activate when the user wants skill definitions checked:

• "Check the ai_instruction_writing skill" / "audit this SKILL.md" / "is this skill's description router-safe?"
• "Check the wiki family skills" / "doctor the task_* skills."
• "Check all skills in this repo" / "skill health-check for the whole tree."

Route cross-harness and cross-OS portability review of bundled runtime artefacts to harness_portability. Route authoring rewrites of instruction prose to ai_instruction_writing / ai_instruction_formatting after this skill reports findings. </when_to_activate>

<path_resolution> Bundled scripts live in scripts/ next to this SKILL.md. Resolve each script's absolute path by combining the directory of this SKILL.md with scripts/<script-name> and invoke that absolute path. If the first invocation reports a missing file, re-resolve the absolute path once before treating the script as failed. </path_resolution>

<check_only> Report findings only. Leave every selected skill artifact, and every other skill file, byte-for-byte unchanged for the duration of a check run. Applying fixes is a separate user-directed edit, never part of this workflow. </check_only>

<scope_resolution> Resolve scope before any check, and name the final target set out loud before continuing.

Every check targets the repository source tree, so pass that repo root as --root and resolve every selector inside it.

The resolver discovers the layout instead of requiring one. It walks the whole tree under --root for skill files, matching the filename case-insensitively the way the harness matches it, and it prunes version-control, dependency, build, and cache directories along with every path the repository itself ignores. It recognizes a plugins/*/skills/ layout, a repo-root skills/ tree, a <vendor-config-dir>/skills/ tree, a single-skill repo whose SKILL.md sits at the top level, and a nested layout below the root, and it reports which layout each resolved skill came from under layouts, so the reader sees what was walked. Where a plugin manifest sits above a resolved skill, the payload records it as that skill's plugin_host, and the registration step reads that association. A copy of a skill deployed under a vendor configuration directory outside the repo root is a build output rather than a target, so a selector pointing at one resolves the repository source of the same name and reports the swap under vendor_substitution; name that substitution in the orientation lead.

• Single skill. A request that names one skill or one skill-file / skill-directory path stays on that skill. Run scripts/resolve_scope.py --root <repo-root> --skill <name-or-path>.

• Family. A request that names a family token expands to the matching sibling set. A family hub is the skill whose frontmatter name: equals the family token. Skills share that family-name when their frontmatter name: equals the token or equals the token followed by _ and a non-empty suffix (token_*). Resolve a family as the set of skill directories the walk found whose skill names share that family-name, unioned with any skills named in the hub SKILL.md <family> block when that hub and block exist; when no hub or no <family> block is present, use that family-name set alone. Run scripts/resolve_scope.py --root <repo-root> --family <token>.

  The resolver identifies that <family> block structurally rather than by first occurrence: the opening tag has to own its line, outside every fenced code block and inline code span, and a closing tag has to follow it. An author may therefore document the tag freely (naming <family> in prose, quoting it in backticks, or showing a whole example block inside a fence) and contribute no members. A body carrying an opening tag with no closing tag declares no block at all and resolves by name prefix alone. Members come from the leading backticked token of each block list item, so a trailing mention such as - `task_finish`: bump `updated` declares one name rather than two.