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.
--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 0.1.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.
1---2argument-hint: "[--root PATH ...] [--format text|json] [--fix-safe] [--dependencies-only]"3compatibility: Requires ai-skillet 0.1.0+.4name: skill-doctor-35description:6 "Use to audit Agent Skills catalogs or installed skill roots for metadata and doc-link issues; optionally apply7 conservative --fix-safe repairs."8metadata:9 source: https://skillmd.com/skills/gabrielmoreira/skill-doctor-310---1112# Skill Doctor1314Use ai-skillet's canonical validator for the supported extended skill dialect to audit local catalogs and installed15skill roots, then apply only narrow metadata repairs when requested.1617## Arguments1819- `--root PATH`: Scan this catalog or installed skill root. Repeatable. Default: current working directory.20- `--format text|json`: Select report format. Default: `text`.21- `--fix-safe`: Create missing `agents/openai.yaml` files or update mismatched `policy.allow_implicit_invocation`.22- `--dependencies-only`: Report only malformed or unresolved `skill-dependencies` declarations. Do not combine with23 `--fix-safe`.2425## Workflow26271. Require `ai-skillet` 0.1.0 or newer on `PATH`, then run:2829 ```sh30 ai-skillet doctor31 ```3233 Append each parsed invocation option and its value as separate arguments, preserving quoted values. For example,34 `--root '/path with spaces' --format json` adds two options; use the argument-free form for the defaults.35362. Use JSON when another command or agent will consume the result:3738 ```sh39 ai-skillet doctor --root . --format json40 ```41423. Run safe fixes only after reading the findings:4344 ```sh45 ai-skillet doctor --root . --fix-safe46 ```47484. Re-run without `--fix-safe` after any manual edits.4950For a dependency-only catalog gate, run:5152```sh53ai-skillet doctor --root . --dependencies-only54```5556## Findings5758- Treat `error` findings as catalog defects that should block publishing or syncing.59- Treat `warning` findings as review-required catalog hygiene issues.60- JSON output uses schema version 1 with structured roots, counts, findings, and safe-fix records. Each finding carries61 its code, severity, path, line when known, fixability, and message.62- Frontmatter validation accepts the portable Agent Skills fields, Claude Code extensions, and repository extensions as63 one supported union. It reports unknown top-level fields; invalid field, item, and metadata-value types; invalid64 enumerated values; and `agent` or `background` used without `context: fork`.65- Explicit `disable-model-invocation: false` and `user-invocable: true` produce redundant-default warnings. Omit those66 fields to preserve the same effective defaults.67- Prompt-hygiene warnings are advisory and never auto-fix: stale model pins, oversized unconditional Markdown68 references, conflicting requirement/prohibition language, and missing completion evidence.69- Coordination-exemption errors are report-only: `coordination: exempt` must be paired with the catalog's canonical70 `coordination-exempt` sentence in ordinary Markdown prose. Inline code, fenced or indented code, blockquotes, and71 headed `Example` or `Examples` sections do not count as declarations. Neither side is repaired by `--fix-safe`.72- Dependency errors reject non-array, empty, non-string, duplicate, malformed, incorrectly ordered, self-referential, or73 unresolved local declarations. External `ORG/REPO#SKILL` identifiers are shape-checked without network access.74- Metadata, OpenAI policy, coordination, resource, README, prompt-hygiene, and CLI-version checks remain available75 outside `--dependencies-only`.76- Use `path` and `line` from JSON output for precise follow-up edits.7778## Safe Fix Policy7980`--fix-safe` may only:8182- Create a missing `agents/openai.yaml` with `policy.allow_implicit_invocation` derived from `SKILL.md`.83- Update an existing `allow_implicit_invocation` boolean when it disagrees with `disable-model-invocation`.8485Each permitted repair is staged and atomically renamed into place, preserving the target's permissions for updates. A86failed safe fix exits 3 without partially rewriting its target.8788`--fix-safe` does not rewrite frontmatter, descriptions, README rows, `references/version.txt`, or relative links.89Unknown fields, invalid types or values, cross-field errors, redundant defaults, and coordination declarations are90report-only. Make those edits manually and verify with a fresh audit.9192## Related Skills9394- `skill-doctor` only audits the roots you pass; it does not search for them. To locate skill installs, duplicates, and95 cross-references across the machine, use `ai-skillet map`.9697## Exit Codes9899- `0`: Clean, or all requested safe fixes succeeded and no findings remain.100- `1`: The audit completed and findings remain; report them as review work, not as an operational crash.101- `2`: Invalid arguments or unreadable environment.102- `3`: A requested safe fix failed.103104## User-Facing Output105106Keep `--format json` byte-valid and undecorated. For human output, lead with `### 🩺 Skill Doctor — ✅ clean`,107`### 🩺 Skill Doctor — ⚠️ review required`, or `### 🩺 Skill Doctor — ⛔ blocked` for exit 2/3, then show roots and108error/warning/fix counts in a compact table. List safe fixes separately from remaining findings. For review-required or109blocked outcomes, end with the smallest manual next action; for a clean result, stop after the summary. Keep paths, line110numbers, codes, raw findings, commands, and diagnostics exact.