skill-doctor
installsforks
How to install skill-doctor?
paulrberg/agent-skills/skill-doctor
$npx -y skills add PaulRBerg/agent-skills --skill skill-doctorUse to audit Agent Skills catalogs or installed skill roots for metadata and doc-link issues; optionally apply conservative --fix-safe repairs.
SKILL.md
| 1 | # Skill Doctor |
| 2 | |
| 3 | Audit local Agent Skills catalogs and installed skill roots, then apply only narrow metadata repairs when requested. |
| 4 | |
| 5 | ## Arguments |
| 6 | |
| 7 | - `--root PATH`: Scan this catalog or installed skill root. Repeatable. Default: current working directory. |
| 8 | - `--format text|json`: Select report format. Default: `text`. |
| 9 | - `--fix-safe`: Create missing `agents/openai.yaml` files or update mismatched `policy.allow_implicit_invocation`. |
| 10 | |
| 11 | ## Workflow |
| 12 | |
| 13 | 1. Resolve the skill directory, then run the helper from that directory: |
| 14 | |
| 15 | ```sh |
| 16 | uv run scripts/skill-doctor.py "$ARGUMENTS" |
| 17 | ``` |
| 18 | |
| 19 | 2. Use JSON when another command or agent will consume the result: |
| 20 | |
| 21 | ```sh |
| 22 | uv run scripts/skill-doctor.py --root . --format json |
| 23 | ``` |
| 24 | |
| 25 | 3. Run safe fixes only after reading the findings: |
| 26 | |
| 27 | ```sh |
| 28 | uv run scripts/skill-doctor.py --root . --fix-safe |
| 29 | ``` |
| 30 | |
| 31 | 4. Re-run without `--fix-safe` after any manual edits. |
| 32 | |
| 33 | ## Findings |
| 34 | |
| 35 | - Treat `error` findings as catalog defects that should block publishing or syncing. |
| 36 | - Treat `warning` findings as review-required catalog hygiene issues. |
| 37 | - Prompt-hygiene warnings are advisory and never auto-fix: stale model pins, oversized unconditional Markdown |
| 38 | references, conflicting requirement/prohibition language, and missing completion evidence. |
| 39 | - Use `path` and `line` from JSON output for precise follow-up edits. |
| 40 | |
| 41 | ## Safe Fix Policy |
| 42 | |
| 43 | `--fix-safe` may only: |
| 44 | |
| 45 | - Create a missing `agents/openai.yaml` with `policy.allow_implicit_invocation` derived from `SKILL.md`. |
| 46 | - Update an existing `allow_implicit_invocation` boolean when it disagrees with `disable-model-invocation`. |
| 47 | |
| 48 | Do not use the helper to rewrite frontmatter order, descriptions, README rows, `references/version.txt`, or relative |
| 49 | links. Make those edits manually and verify with a fresh audit. |
| 50 | |
| 51 | ## Related Skills |
| 52 | |
| 53 | - `skill-doctor` only audits the roots you pass; it does not search for them. To locate skill installs, duplicates, and |
| 54 | cross-references across the machine, use the `skill-map` skill when it is installed. |
| 55 | |
| 56 | ## Exit Codes |
| 57 | |
| 58 | - `0`: Clean, or all requested safe fixes succeeded and no findings remain. |
| 59 | - `1`: The audit completed and findings remain; report them as review work, not as an operational crash. |
| 60 | - `2`: Invalid arguments or unreadable environment. |
| 61 | - `3`: A requested safe fix failed. |
| 62 | |
| 63 | ## User-Facing Output |
| 64 | |
| 65 | Keep `--format json` byte-valid and undecorated. For human output, lead with `### 🩺 Skill Doctor — ✅ clean`, |
| 66 | `### 🩺 Skill Doctor — ⚠️ review required`, or `### 🩺 Skill Doctor — ⛔ blocked` for exit 2/3, then show roots and |
| 67 | error/warning/fix counts in a compact table. List safe fixes separately from remaining findings. For review-required or |
| 68 | blocked outcomes, end with the smallest manual next action; for a clean result, stop after the summary. Keep paths, line |
| 69 | numbers, codes, raw findings, commands, and diagnostics exact. |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
