Docs doctor
Audits a repository's documentation for unused docs, wrong details, missing coverage, inaccurate data, broken structure, and writing best-practices. Generates a markdown report (HTML optional) with severity ratings. Supports modes (main, comprehensive, focused, quick), per-profile templates (open-source, internal-docs, blog, nextjs-app), optional --fix for low-risk auto-fixes (broken links, frontmatter, stale dates), and a /feedback subcommand that promotes recurring signals into Learned defaults. Use when you want a "docs doctor" pass on a repo before a release, after a refactor, or as a recurring DX health check.From its SKILL.md
npx -y skills add mostafa-drz/claude-skills --skill docs-doctorAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
3 things to look at
- skips confirmationTells the agent to proceed without asking first, 2 times: "apply all allowlisted fixes without prompting" and 1 more.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
- runs commandsInstructs the agent to run 2 commands, including `git rev-parse --show-toplevel` and 1 more.
SKILL.md
14.5 KB, ~3.4k tokens by cl100k_base, as published. Nobody here has run it
Docs Doctor
Audit a repository's documentation like a doctor: triage what's missing, wrong, stale, structurally broken, or written badly. Produce a severity-ranked report; optionally apply low-risk fixes. Configurable by mode, scope, and template profile. Learns from your feedback over time.
Preferences
On startup, use the Read tool to load ~/.claude/skills/docs-doctor/preferences.md. If missing, treat as "no preferences set" and continue with Defaults below.
Context
On startup, use the Bash tool to detect: git repo root (git rev-parse --show-toplevel), current branch, and whether package.json / pyproject.toml / Cargo.toml / go.mod is present (for code-doc check selection). Use the Glob tool to list **/*.md, **/*.mdx, and any CLAUDE.md / AGENT.md files. Skip any detection step that fails — do not abort.
Command routing
Check $ARGUMENTS:
help→ display help, then stopconfig→ interactive setup, then stopreset→ delete~/.claude/skills/docs-doctor/preferences.md,feedback-journal.md,sessions/,resume-state.md, confirm, stopfeedback→ run the feedback flow (see § Feedback & learning), then stoptemplates→ list available templates from~/.claude/skills/docs-doctor/templates/, then stopresume→ ifresume-state.mdexists, continue the last interrupted run; else sayNo session to resume.--from-template=<name>→ load template, merge with flags, run- anything else (including empty) → run the audit
Help
Docs Doctor — audits repository documentation and produces a severity-ranked report
Usage:
/docs-doctor Interactive audit (asks for mode)
/docs-doctor --mode=main Default audit (6 core categories)
/docs-doctor --mode=comprehensive Adds link-check, code-doc drift, freshness vs git
/docs-doctor --mode=quick Smoke check (broken links + frontmatter + stale dates)
/docs-doctor --mode=focused --category=missing-docs
Run a single category
/docs-doctor --from-template=nextjs-app Use a preset profile
/docs-doctor --scope=markdown,frontmatter Limit doc types audited
/docs-doctor --fix Apply low-risk auto-fixes after report
/docs-doctor --html Also emit interactive HTML report
/docs-doctor templates List available templates
/docs-doctor feedback Rate the most recent session
/docs-doctor resume Continue an interrupted run
/docs-doctor config Set preferences
/docs-doctor reset Clear preferences + journal + sessions
/docs-doctor help This help
Categories (for --category):
unused-docs, wrong-details, missing-docs, inaccurate-data,
missing-structure, best-practices
Current preferences:
(loaded from ~/.claude/skills/docs-doctor/preferences.md)
Config
Use AskUserQuestion to collect:
- Q1 — Default mode:
main/comprehensive/quick - Q2 — Default scope (multiSelect): markdown, frontmatter, code-docs, agent-instructions
- Q3 — Default output: markdown / html / both
- Q4 — Severity threshold (what's shown in report):
info+/warn+/error-only - Q5 — Fix policy:
never(report only) /interactive(ask per fix) /auto-low-risk(apply allowed fixes without prompt) - Q6 — Ignored path globs (comma-separated, e.g.
node_modules/**, vendor/**, .next/**)
Write to ~/.claude/skills/docs-doctor/preferences.md in the three-tier format (see § Preferences file format below).
Reset
Use the Bash tool to delete the skill's state files:
~/.claude/skills/docs-doctor/preferences.md~/.claude/skills/docs-doctor/feedback-journal.md~/.claude/skills/docs-doctor/sessions/~/.claude/skills/docs-doctor/resume-state.md
Confirm: State cleared. Using defaults next run.
First-time detection
If preferences.md does not exist:
First time using
/docs-doctor? Run/docs-doctor configto set defaults, or continue with sensible defaults (mode=main, scope=markdown+frontmatter+agent-instructions, output=markdown, severity=warn+, fix=never).
Then proceed.
Defaults
- mode:
main - scope:
markdown, frontmatter, agent-instructions - output:
markdown - severity threshold:
warn+ - fix policy:
never - ignored paths:
node_modules/**, vendor/**, dist/**, build/**, .next/**, .turbo/**, coverage/**
Workflow
Step 0 — Load learning context
Read~/.claude/skills/docs-doctor/preferences.md— apply Defaults / Profile / Learned in that order (Learned wins).Read~/.claude/skills/docs-doctor/feedback-journal.md— note any recurringSignal:lines to bias severity and category emphasis.- If either file is missing, continue silently with Defaults.
Step 1 — Resolve run config
- Parse flags from
$ARGUMENTS. - If
--from-template=<name>:Read~/.claude/skills/docs-doctor/templates/<name>.md, merge template values under flags (flags override template). - If
--modeis unset and not in preferences: useAskUserQuestionto pick mode. Pre-select theLearnedmode if one exists, elsemain. - If
--categoryis set but--modeis notfocused, set--mode=focused. - Compute final config object:
{ mode, scope, output, severity_threshold, fix_policy, ignored_paths, categories, target_files }.
Step 2 — Discover docs
- Use
Globto enumerate candidate files based on scope:markdown:**/*.md,**/*.mdxfrontmatter: subset of markdown that starts with---code-docs:**/*.{ts,tsx,js,jsx,py,rs,go}(filter by detected project type)agent-instructions:**/CLAUDE.md,**/AGENT.md,**/AGENTS.md
- Remove anything matching
ignored_paths. - If zero files: stop with
No docs found in scope. Check --scope or --ignored.
Step 3 — Run checks
For each enabled category, run the corresponding checks defined in reference/checks.md. Categories enabled by mode:
| Mode | Categories |
|---|---|
| quick | wrong-details (broken-links subset), missing-structure (frontmatter only), inaccurate-data (dates) |
| main | all 6 core: unused-docs, wrong-details, missing-docs, inaccurate-data, missing-structure, best-practices |
| comprehensive | main + freshness-vs-git, external-link-check, code-doc-drift, onboarding-flow, search-ability |
| focused | only the category passed via --category |
Each check returns findings with: { file, line?, category, severity, rule, message, suggested_fix? }.
Run checks in parallel where independent (e.g. file-level reads can batch). Use Grep for pattern checks across files, Read for per-file inspection. Defer external network checks (WebFetch) to last; cap to 25 URLs per run unless --mode=comprehensive.
Step 4 — Score and rank
- Apply severity rules from
reference/severity.md. - Filter out findings below
severity_threshold. - Sort by severity (error → warn → info), then by category, then by file.
- Compute summary counts: total, by severity, by category.
Step 5 — Write report
- Create
<repo>/.docs-doctor/if missing. Ensure it's in.gitignore(offer to add if not). - Write markdown report to
<repo>/.docs-doctor/report-<YYYY-MM-DD-HHMM>.mdwith sections:- Header (mode, scope, severity threshold, ignored paths)
- Executive summary (counts, top 5 issues)
- Findings grouped by category, each with severity badge, file:line, rule, message, suggested fix
- Fix plan (if
--fixrequested)
- If
--htmlor output preference ishtml/both, also write<repo>/.docs-doctor/report-<ts>.html— single-file HTML with chip filters per severity/category (matches Decision Report pattern: hero summary, inline JS filters, gray-out-on-change). - Save session log:
~/.claude/skills/docs-doctor/sessions/<YYYY-MM-DD-HHMM>.mdwith: config used, counts, top findings, decisions taken, follow-ups.
Step 6 — Optional --fix pass
If --fix was passed and fix_policy ≠ never:
- Filter findings to those with
suggested_fixAND rule in the auto-fixable allowlist:broken-internal-linkfrontmatter-missing-required(only safe defaults)frontmatter-key-disorderstale-last-updated
- If
fix_policy = interactive: for each fix, show diff viaAskUserQuestion(Apply / Skip / Apply all remaining). - If
fix_policy = auto-low-risk: apply all allowlisted fixes without prompting; record them in the report. - Use
Editfor file changes. NeverWriteover a file unless creating a new doc the user approved. - After all fixes, re-run only the touched checks to confirm.
- Append a "Fixes applied" section to the report.
Destructive or wide-blast fixes (deleting whole docs, rewriting paragraphs) are never auto-applied — always require explicit confirmation.
Step 7 — Final summary
Print to chat:
Docs Doctor: <mode> mode on <N> files
Errors: X · Warnings: Y · Info: Z
Top issues: <one-liners for top 3>
Report: .docs-doctor/report-<ts>.md
Fixes applied: <count> (if --fix)
Then ask via AskUserQuestion:
- Open report? Yes / Open in browser (HTML) / No
Step 8 — Invite feedback
End with one line:
Run
/docs-doctor feedback— even one rating helps me sharpen severity and category emphasis for this repo.
Templates
Templates live in ~/.claude/skills/docs-doctor/templates/<name>.md. Each template declares default flags as YAML frontmatter:
---
name: <template-name>
description: <one-liner>
inputs: { mode, scope, severity_threshold, fix_policy }
tasks: [ordered-check-keys]
constraints: [rules]
ignored_paths: [globs]
postProcesses: [open-report, append-to-changelog]
---
Loading: when --from-template=<name> is passed, Read the file, parse the frontmatter, merge values under the workflow config (CLI flags still win).
Shipped templates:
open-source.md— emphasises README, CONTRIBUTING, LICENSE, public API docsinternal-docs.md— emphasises onboarding, runbooks, ADRsblog.md— content-first: frontmatter completeness, broken images, draft markers, datesnextjs-app.md— Next.js conventions: route-level docs, app/page coverage, CLAUDE.md sanity
To add a template: drop a new file in templates/ matching the schema above. List them via /docs-doctor templates.
Preferences file format
# /docs-doctor preferences
Updated: YYYY-MM-DD
## Defaults
- mode: main
- scope: markdown, frontmatter, agent-instructions
- output: markdown
- severity_threshold: warn+
- fix_policy: never
- ignored_paths: node_modules/**, dist/**, .next/**
## Profile (optional — edit freely)
- (user-editable lines: bias which categories matter, custom severity per repo)
## Learned
- (populated from feedback; promoted after 3+ consistent signals)
Feedback & learning
When invoked as /docs-doctor feedback:
- Find the most recent
~/.claude/skills/docs-doctor/sessions/<YYYY-MM-DD-HHMM>.md. If none, sayNo recent session found.and stop. - Print a one-line summary of that session (mode, file count, top issues).
- Ask via
AskUserQuestionin one batch (4 questions):- Category usefulness (multiSelect): which categories were signal vs noise?
- Severity calibration: too strict / about right / too lenient
- Auto-fix accuracy (only if
--fixwas used): all correct / some wrong / no fixes applied - Output format preference: keep markdown / prefer HTML / want both / want shorter summary
- Append to
~/.claude/skills/docs-doctor/feedback-journal.md:## <session slug> — <YYYY-MM-DD> - Mode: <mode> - Useful categories: <list> - Noisy categories: <list> - Severity calibration: <answer> - Auto-fix accuracy: <answer> - Output preference: <answer> - Signal: <one-line generalisation of the takeaway> - Promotion rule: when 3+ sessions share the same
Signal:, promote it to## Learnedinpreferences.mdand tell the user once:Noticed you consistently <signal>. Saved as standing default. - Drift correction: when a
Learnedrule is contradicted in 2 newer sessions, demote it back to inactive and log the demotion in the journal asSignal: demoted "<rule>" — contradicted by <session-1>, <session-2>.
Principles
- Manifest first — every audit run produces a report file; the conversation is the index, not the source of truth.
- Graceful degradation — missing preferences / journal / templates never block a run; fall back to Defaults silently.
- Learn quietly — promote a rule only after 3+ consistent signals; mention once, never twice.
- No fabricated structure — if scope or mode is ambiguous, ask via
AskUserQuestionrather than invent. - Destructive actions need confirmation — auto-fix is gated to a strict allowlist; anything else asks first.
- Stop means stop — if the user halts mid-audit, write
resume-state.mdwith progress so/docs-doctor resumecan continue. - Skill orchestrates, does not re-judge — when fixing, preserve user-authored content; never rewrite prose silently.
- Detail lives in reference/ — keep this SKILL.md under 500 lines; deep check definitions live in
reference/checks.mdandreference/severity.md.
What ships with it: 7 files
20.4 KB alongside SKILL.md
reference/
- checks.md8.8 KB
- severity.md2.3 KB
templates/
- blog.md2.0 KB
- internal-docs.md2.0 KB
- nextjs-app.md2.6 KB
- open-source.md2.0 KB
- icon.svg806 B