audit-docs
/audit-docs
Audit README.md and docs/ for accuracy. Runs every documented code example, checks links, anchors, and prose rules, and verifies the CLI examples against the built gem. Use when documentation changes, before a release, or when the user asks to check the docs, verify code samples, or confirm the examples still work.
- Author
- cardmagic ↗
- Repository
- classifier ↗
- Licence
- LGPL
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
LGPL, otwarta.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: check_docs.rb
What it does and when to use it
Audit README.md and docs/ for accuracy. Runs every documented code example, checks links, anchors, and prose rules, and verifies the CLI examples against the built gem. Use when documentation changes, before a release, or when the user asks to check the docs, verify code samples, or confirm the examples still work.
Original author description
Audit README.md and docs/ for accuracy. Runs every documented code example, checks links, anchors, and prose rules, and verifies the CLI examples against the built gem. Use when documentation changes, before a release, or when the user asks to check the docs, verify code samples, or confirm the examples still work.
How it works
- 1. Run the executable examples
- 2. Run the static checks
- 3. Run the full suite
- 4. Verify the CLI examples against a real install
- 5. Cross-check new public API
- Reporting
SKILL.md preview
--- name: audit-docs description: Audit README.md and docs/ for accuracy. Runs every documented code example, checks links, anchors, and prose rules, and verifies the CLI examples against the built gem. Use when documentation changes, before a release, or when the user asks to check the docs, verify code samples, or confirm the examples still work. --- # Audit the documentation The docs make claims about how this gem behaves. This audit proves each claim or finds the ones that are false. A documented example that no longer runs is a bug. Fix the code or fix the docs. Never weaken an assertion to make a check pass. ## 1. Run the executable examples `test/docs/documentation_test.rb` holds one assertion per value printed in README.md and docs/*.md. ```bash bundle exec ruby -Ilib -Itest test/docs/documentation_test.rb ``` Every failure means the docs and the code disagree. Read the failure, decide which side is wrong, and correct that side. ## 2. Run the static checks ```bash ruby .claude/skills/audit-docs/check_docs.rb ``` This covers what a unit test cannot: - em dashes and en dashes, which this repo's prose rules forbid - relative markdown links that point at a missing file - link fragments that point at a missing heading - documented executables that do not exist ## 3. Run the full suite ```bash bundle exec rake test bundle exec rubocop ``` The documentation test is part of `rake test`, so a red suite blocks a release. ## 4. Verify the CLI examples against a real install The shell examples are not covered by the unit test. Build the gem, install it into a throwaway `GEM_HOME`, and run the commands as a new user would. ```bash gem build classifier.gemspec export GEM_HOME=$(mktemp -d) GEM_PATH=$GEM_HOME PATH=$GEM_HOME/bin:$PATH gem install classifier-*.gem --no-document ``` Then walk the examples in `docs/cli.md` and `docs/keywords.md` in order, from an empty directory. Order matters. A reader runs the commands top to bottom, so a command that needs a model must come after the command that builds one. Check that: - the first example a new user meets actually succeeds - printed output matches what the page shows - exit codes match the documented table - an error path prints the documented message Delete the temporary `GEM_HOME` and the built `.gem` when finished. ## 5. Cross-check new public API List what the code exposes and confirm the docs cover it: ```bash grep -rn "^\s*def \(self\.\)\?[a-z_]" lib/classifier/*.rb | grep -v "def _" ``` Anything public and undocumented is a gap. Add it to the right page in `docs/` and add an assertion to `test/docs/documentation_test.rb`. ## Reporting Report every finding with the file, the claim, and the observed behavior. Say plainly which side you changed. If the audit finds nothing, say the docs are accurate and name what you verified, so the result is checkable.
Files in this package (2)
- SKILL.md 3 KB
- check_docs.rb 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · cardmagic/classifier | 100 | LGPL |
| opsmill/infrahub | 100 | Apache-2.0 |
| TalonT-Org/AutoSkillit | 100 | MIT |
| umep-dev/suews | 95 | MPL-2.0 |
Database snapshot: 13.11.2026 · package version 543949d2722b (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100docs-sync
Use when the user asks to update documentation after code or configuration changes, audit documentation drift, or prepare README, API, runbook, or release docs. Changes only affected documentation and verifies examples, links, contracts, and operational steps against source code. - 100docs-sync-audit
Run a read-only documentation drift audit for a feature, PR, branch, release, API, configuration change, workflow, CLI, package, or repository area. Use when the user asks whether docs are stale, missing, inconsistent with code, or need updates after code changes. Checks README… - 100review-docs
Review documentation (README.md, agent-instructions files — CLAUDE.md, AGENTS.md, or the harness's equivalent — and .claude/rules/) for accuracy, drift against the codebase, and context cost. Use whenever the user asks to review or audit docs, check documentation, validate a… - 100refresh-repo-docs
Audit and sync a repo's human-facing documentation (README, docs/, CHANGELOG, CONTRIBUTING, examples) against the actual code — detect drift deterministically, fix stale claims, remove cruft, fill gaps, and verify every claim written. Use when docs are outdated, after major… - 100docs-sync
Audit and update Argus user-facing docs (README, docs/**/*.md, site/*.html) against the code truth. Detects version drift, command-count drift, i18n parity violations, and stale CLI examples. Use before a release, or any time the user asks to "sync docs", "update docs", "fix… - 90check-docs
Check if documentation (README.md, AGENTS.md, docs/) is up to date with recent code changes. Use when code has been modified and docs may be stale.