docs-audit_skill

Overview

This skill performs a comprehensive documentation audit against the current code state, producing a structured report with prioritized findings. It checks markdown accuracy, link validity, code example correctness, and docstring coverage while minimizing context usage. Reports are scaffolded and written to .pack/reports/ by default, with multi-file and custom-output options.

How this skill works

It discovers markdown files with git metadata, prioritizes a target set (stale, recent, or all), and runs deep analysis on the selected files. Deep checks include correctness of code examples and CLI snippets, internal link and anchor validation, completeness checks for required sections and exports, and docstring coverage scanning across detected languages. Findings are compiled into a YAML-frontmatter report (single or multi-file) and written to the generated path; a short summary and paths are returned for quick review.

When to use it

• Before a release to ensure docs match code changes
• When merging large refactors that may break examples or signatures
• Periodic health checks on a documentation-heavy repo
• Preparing onboarding or public-facing docs for customers
• Investigating reports of broken links or outdated instructions

Best practices

• Run discovery first to scope and prioritize rather than scanning everything
• Use focus and limit flags to target highest-risk docs (stale or recent)
• Prefer multi-file mode for detailed audits and single-file for quick runs
• Keep .pack/reports/ gitignored for ephemeral runs, commit only curated reports
• Create follow-up tasks for critical blocking issues to track fixes

Example use cases

• Audit docs/ after API changes to update function signatures and examples
• Run stale-focused audit on large monorepo to find docs lagging behind code
• Generate a multi-file audit before a public launch to surface missing examples and docstrings
• Run a quick link-only pass to fix internal anchors and image references
• Measure docstring coverage per language to prioritize documentation workstreams