Skill Doctor

Use ai-skillet's canonical validator for the supported extended skill dialect to audit local catalogs and installed skill roots, then apply only narrow metadata repairs when requested.

Arguments

--root PATH: Scan this catalog or installed skill root. Repeatable. Default: current working directory.
--skill NAME: Restrict diagnostics and fixes to this skill directory name. Repeatable.
--format text|json: Select report format. Default: text.
--fix-safe: Create missing agents/openai.yaml files or update mismatched policy.allow_implicit_invocation.
--dependencies-only: Report only malformed or unresolved skill-dependencies declarations. Do not combine with --fix-safe.

Workflow

Require ai-skillet 1.0.0 or newer on PATH, then run:
```
ai-skillet doctor
```
Append each parsed invocation option and its value as separate arguments, preserving quoted values. For example, --root '/path with spaces' --format json adds two options; use the argument-free form for the defaults.
Use JSON when another command or agent will consume the result:
```
ai-skillet doctor --root . --format json
```
Run safe fixes only after reading the findings:
```
ai-skillet doctor --root . --fix-safe
```
Re-run without --fix-safe after any manual edits.

For a dependency-only catalog gate, run:

ai-skillet doctor --root . --dependencies-only

Findings

Treat error findings as catalog defects that should block publishing or syncing.
Treat warning findings as review-required catalog hygiene issues.
JSON output uses schema version 1 with structured roots, counts, findings, and safe-fix records. Each finding carries its code, severity, path, line when known, fixability, and message.
Frontmatter validation accepts the portable Agent Skills fields, Claude Code extensions, and repository extensions as one supported union. It reports unknown top-level fields; invalid field, item, and metadata-value types; invalid enumerated values; and agent or background used without context: fork.
Explicit disable-model-invocation: false and user-invocable: true produce redundant-default warnings. Omit those fields to preserve the same effective defaults.
Prompt-hygiene warnings are advisory and never auto-fix: stale model pins, oversized unconditional Markdown references, conflicting requirement/prohibition language, and missing completion evidence.
Coordination-exemption errors are report-only: coordination: exempt must be paired with the catalog's canonical coordination-exempt sentence in ordinary Markdown prose. Inline code, fenced or indented code, blockquotes, and headed Example or Examples sections do not count as declarations. Neither side is repaired by --fix-safe.
Dependency errors reject non-array, empty, non-string, duplicate, malformed, incorrectly ordered, self-referential, or unresolved local declarations. External ORG/REPO#SKILL identifiers are shape-checked without network access.
Metadata, OpenAI policy, coordination, resource, README, prompt-hygiene, and CLI-version checks remain available outside --dependencies-only.
Use path and line from JSON output for precise follow-up edits.

Safe Fix Policy

--fix-safe may only:

Create a missing agents/openai.yaml with policy.allow_implicit_invocation derived from SKILL.md.
Update an existing allow_implicit_invocation boolean when it disagrees with disable-model-invocation.

Each permitted repair is staged and atomically renamed into place, preserving the target's permissions for updates. A failed safe fix exits 3 without partially rewriting its target.

--fix-safe does not rewrite frontmatter, descriptions, README rows, references/version.txt, or relative links. Unknown fields, invalid types or values, cross-field errors, redundant defaults, and coordination declarations are report-only. Make those edits manually and verify with a fresh audit.

Related Skills

skill-doctor only audits the roots you pass; it does not search for them. To locate skill installs, duplicates, and cross-references across the machine, use ai-skillet map.

Exit Codes

0: Clean, or all requested safe fixes succeeded and no findings remain.
1: The audit completed and findings remain; report them as review work, not as an operational crash.
2: Invalid arguments or unreadable environment.
3: A requested safe fix failed.

User-Facing Output

Keep --format json byte-valid and undecorated. For human output, lead with ### 🩺 Skill Doctor — ✅ clean, ### 🩺 Skill Doctor — ⚠️ review required, or ### 🩺 Skill Doctor — ⛔ blocked for exit 2/3, then show roots and error/warning/fix counts in a compact table. List safe fixes separately from remaining findings. For review-required or blocked outcomes, end with the smallest manual next action; for a clean result, stop after the summary. Keep paths, line numbers, codes, raw findings, commands, and diagnostics exact.

skill-doctor