Proposal: installed-skill doctor (read-only install diagnostics)

[mvanhorn]

Motivation

Users can install a skill successfully and still end up with a broken workflow. Recent issues show missing transitive skills (#1012, #685), a skill present on disk but absent from the host's invokable list (#946), host built-ins shadowing shorthand names (#1019 / also #483 for /code-review), and metadata that works in one harness and fails in another (#360, #965, #993).

Community signal from the last 30 days points the same way: distribution and provenance pain is louder than workflow-quality complaints. Duplicate installs across Claude Code and skills.sh, updates overwriting local edits, lost author metadata, and host config mismatches (CLAUDE.md vs AGENTS.md) keep showing up. Today these are diagnosed one report at a time.

Proposed solution

Add a read-only skill-doctor command/skill that inspects the active installation and reports exact failures with concrete repair advice, without changing files.

Checks:

1. Parse each SKILL.md frontmatter and validate keys against a selected host profile (claude-code, codex, or portable).
2. Build a dependency graph from explicit Skill-tool calls and documented prerequisites; report missing nodes and cycles.
3. Compare plugin manifests, docs catalog, ask-matt routing, and on-disk skills for drift.
4. Detect duplicate local/plugin copies and skill names that collide with a supplied host built-in list.
5. Distinguish working, installed-but-unreachable, missing-dependency, metadata-invalid, and shadowed outcomes.
6. Print repair commands as advice only; never install, delete, or rewrite anything.

Out of scope: auto-fixing installs, mutating CLAUDE.md/AGENTS.md, selective installers (related but separate from #159/#1012).

Happy to open a draft PR if this diagnostic shape looks right. Looking for maintainer signal before writing code.