agentsclimarketplace

Docs doctor

Skill mostafa-drz/claude-skills/code/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

Install
npx -y skills add mostafa-drz/claude-skills --skill docs-doctor

Assembled 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 stop
  • config → interactive setup, then stop
  • reset → delete ~/.claude/skills/docs-doctor/preferences.md, feedback-journal.md, sessions/, resume-state.md, confirm, stop
  • feedback → run the feedback flow (see § Feedback & learning), then stop
  • templates → list available templates from ~/.claude/skills/docs-doctor/templates/, then stop
  • resume → if resume-state.md exists, continue the last interrupted run; else say No 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 config to 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

  1. Read ~/.claude/skills/docs-doctor/preferences.md — apply Defaults / Profile / Learned in that order (Learned wins).
  2. Read ~/.claude/skills/docs-doctor/feedback-journal.md — note any recurring Signal: lines to bias severity and category emphasis.
  3. If either file is missing, continue silently with Defaults.

Step 1 — Resolve run config

  1. Parse flags from $ARGUMENTS.
  2. If --from-template=<name>: Read ~/.claude/skills/docs-doctor/templates/<name>.md, merge template values under flags (flags override template).
  3. If --mode is unset and not in preferences: use AskUserQuestion to pick mode. Pre-select the Learned mode if one exists, else main.
  4. If --category is set but --mode is not focused, set --mode=focused.
  5. Compute final config object: { mode, scope, output, severity_threshold, fix_policy, ignored_paths, categories, target_files }.

Step 2 — Discover docs

  1. Use Glob to enumerate candidate files based on scope:
    • markdown: **/*.md, **/*.mdx
    • frontmatter: 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
  2. Remove anything matching ignored_paths.
  3. 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:

ModeCategories
quickwrong-details (broken-links subset), missing-structure (frontmatter only), inaccurate-data (dates)
mainall 6 core: unused-docs, wrong-details, missing-docs, inaccurate-data, missing-structure, best-practices
comprehensivemain + freshness-vs-git, external-link-check, code-doc-drift, onboarding-flow, search-ability
focusedonly 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

  1. Apply severity rules from reference/severity.md.
  2. Filter out findings below severity_threshold.
  3. Sort by severity (error → warn → info), then by category, then by file.
  4. Compute summary counts: total, by severity, by category.

Step 5 — Write report

  1. Create <repo>/.docs-doctor/ if missing. Ensure it's in .gitignore (offer to add if not).
  2. Write markdown report to <repo>/.docs-doctor/report-<YYYY-MM-DD-HHMM>.md with 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 --fix requested)
  3. If --html or output preference is html/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).
  4. Save session log: ~/.claude/skills/docs-doctor/sessions/<YYYY-MM-DD-HHMM>.md with: config used, counts, top findings, decisions taken, follow-ups.

Step 6 — Optional --fix pass

If --fix was passed and fix_policy ≠ never:

  1. Filter findings to those with suggested_fix AND rule in the auto-fixable allowlist:
    • broken-internal-link
    • frontmatter-missing-required (only safe defaults)
    • frontmatter-key-disorder
    • stale-last-updated
  2. If fix_policy = interactive: for each fix, show diff via AskUserQuestion (Apply / Skip / Apply all remaining).
  3. If fix_policy = auto-low-risk: apply all allowlisted fixes without prompting; record them in the report.
  4. Use Edit for file changes. Never Write over a file unless creating a new doc the user approved.
  5. After all fixes, re-run only the touched checks to confirm.
  6. 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 docs
  • internal-docs.md — emphasises onboarding, runbooks, ADRs
  • blog.md — content-first: frontmatter completeness, broken images, draft markers, dates
  • nextjs-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:

  1. Find the most recent ~/.claude/skills/docs-doctor/sessions/<YYYY-MM-DD-HHMM>.md. If none, say No recent session found. and stop.
  2. Print a one-line summary of that session (mode, file count, top issues).
  3. Ask via AskUserQuestion in 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 --fix was used): all correct / some wrong / no fixes applied
    • Output format preference: keep markdown / prefer HTML / want both / want shorter summary
  4. 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>
    
  5. Promotion rule: when 3+ sessions share the same Signal:, promote it to ## Learned in preferences.md and tell the user once: Noticed you consistently <signal>. Saved as standing default.
  6. Drift correction: when a Learned rule is contradicted in 2 newer sessions, demote it back to inactive and log the demotion in the journal as Signal: demoted "<rule>" — contradicted by <session-1>, <session-2>.

Principles

  1. Manifest first — every audit run produces a report file; the conversation is the index, not the source of truth.
  2. Graceful degradation — missing preferences / journal / templates never block a run; fall back to Defaults silently.
  3. Learn quietly — promote a rule only after 3+ consistent signals; mention once, never twice.
  4. No fabricated structure — if scope or mode is ambiguous, ask via AskUserQuestion rather than invent.
  5. Destructive actions need confirmation — auto-fix is gated to a strict allowlist; anything else asks first.
  6. Stop means stop — if the user halts mid-audit, write resume-state.md with progress so /docs-doctor resume can continue.
  7. Skill orchestrates, does not re-judge — when fixing, preserve user-authored content; never rewrite prose silently.
  8. Detail lives in reference/ — keep this SKILL.md under 500 lines; deep check definitions live in reference/checks.md and reference/severity.md.

What ships with it: 7 files

20.4 KB alongside SKILL.md

reference/

templates/

Keep looking

Skills are one crate of 611,884. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.