ValentinNikolaev/agent-skills / agent-plugins/skills/audit-docs
audit-docs
VerifiedAudit repository docs read-only for broken links and paths, stale indexes or ADR pointers, duplicate canonical facts, migration gaps, and language or script violations defined by repository policy. Not memory stores, code review, or fixes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.7 KB |
| agents/openai.yaml | config | 232 B |
| scripts/check_docs.py | script | 20.3 KB |
SKILL.md
View on GitHub---
name: audit-docs
description: Audit repository docs read-only for broken links and paths, stale indexes or ADR pointers, duplicate canonical facts, migration gaps, and language or script violations defined by repository policy. Not memory stores, code review, or fixes.
---
# Audit Docs
Audit documentation without changing repository or external state.
## Establish Scope
1. Use the user's files, directory, or migration boundary as the primary scope. Otherwise, use `docs/` when it exists.
2. Include repository-level contributor or agent guidance only when it governs documentation behavior.
3. Route memory directories and `MEMORY.md` health checks to `audit-memory` unless the user explicitly includes them in a broader documentation migration.
4. Do not follow symlinks outside the selected repository. Treat unavailable cross-repository provenance as a limitation, not a broken local pointer.
5. Read local documentation policies before checking prohibited languages, Unicode scripts, generated indexes, or ADR conventions. Do not infer a prohibited language or script from cultural or repository context.
## Run Deterministic Checks
Run the bundled read-only checker before manual analysis. Resolve `<skill-dir>` to the directory containing this `SKILL.md`, then run:
```text
python "<skill-dir>/scripts/check_docs.py" [scope ...]
```
Use `--index <index.md> --index-root <directory>` only when the repository defines that file as an index. Use `--prohibited-regex <pattern>` or `--prohibited-range <start-end>` only for an explicit user or repository policy. Use `--format json` when structured output helps downstream analysis.
Treat checker findings as evidence to verify, not automatic conclusions. The checker deliberately excludes fenced and inline code, URLs, absolute paths, placeholders, generated or dependency directories, and prose explicitly marked as historical, external, or provenance-only. Do not report excluded content unless local policy clearly makes it load-bearing.
## Inspect Semantic Drift
1. Compare declared documentation indexes with the current in-scope tree. Run only repository-provided commands explicitly documented as read-only checks; request permission if the command is unavailable under the current tool policy.
2. Find superseded ADRs and report living documentation that presents them as current. Do not flag historical citations that identify their status.
3. Identify duplicate load-bearing facts only when two independent locations claim canonical authority or can change separately. Ignore intentional summaries that point to a canonical source.
4. For migrations, verify whether each requested fact is present somewhere after migration. Report gaps and coverage limits; never certify losslessness.
5. Verify plain path references manually when context is ambiguous. Ignore examples, placeholders, generated output, external provenance, and historical references unless the repository expects them to resolve locally.
## Classify and Report
Use these severities:
- `critical`: a broken local command, file link, required index entry, or current ADR pointer is likely to mislead contributors.
- `warning`: stale, duplicated, or ambiguous canonical documentation is likely to drift.
- `info`: a review opportunity, external provenance concern, or weak signal needs human judgment.
For every finding, include severity, `file:line` evidence, the affected reference or claim, and one sentence explaining impact. Group findings by audit class and include scanned scope, skipped paths, unavailable checks, and other limitations.
If no finding remains after verification, say that no issues were detected in the completed checks. Do not claim that the documentation is certified correct.
Do not edit files, regenerate indexes, stage changes, or run state-changing commands.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |