Skip to content
Skills Library
Programming · Testing

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.

Repository
classifier ↗
Licence
LGPL
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

LGPL, otwarta.

What to check before installing
  • 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. 1. Run the executable examples
  2. 2. Run the static checks
  3. 3. Run the full suite
  4. 4. Verify the CLI examples against a real install
  5. 5. Cross-check new public API
  6. Reporting
Original SKILL.md headings · 84 lines, 408 words
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

RepositoryScoreLicence
This page · cardmagic/classifier100LGPL
opsmill/infrahub100Apache-2.0
TalonT-Org/AutoSkillit100MIT
umep-dev/suews95MPL-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.