docs-check skill
✓ VerifiedPerforms a read-only audit of documentation to detect stale content, broken links, invalid diagrams, and hallucinations against the codebase.
- GitHub stars
- 8
- Files
- 5
- Last commit
- Oct 28, 2026
- License
- MIT
- Allowed tools
- —
What does the docs-check skill do?
docs-check performs a read-only audit of documentation to detect stale content, broken links, invalid diagrams, and hallucinations against the codebase.
Summary generated from the skill's SKILL.md.
About the docs-check skill
Auditing documentation for accuracy and freshness is what developers do with docs-check. This tool performs a read-only inspection of your documentation files, such as README.md, ADRs, and RFCs, to ensure they align with the actual state of your codebase. It is designed for engineers performing documentation reviews, preparing for new team member onboarding, or conducting pre-release health checks.
The process involves scanning your documentation directory, detecting your technology stack from files like Dockerfiles or package files, and verifying claims against real code. It checks for broken internal links, invalid Mermaid diagram syntax using mmdc, and unreplaced placeholders. Unlike tools that modify files, this skill only generates reports that categorize documents as Good, Stale, Broken, or Missing.
When an agent loads this skill, it uses tools like git, grep, and glob to cross-reference component names, file paths, and numeric counts. If a discrepancy is found, the tool produces a detailed hallucination report and provides specific recommendations for follow-up actions using other commands like docs-update.
What an agent can do with it
- 1Detect documentation hallucinationsVerify if your documentation makes false claims about the number of services or existing file paths.
- 2Identify stale documentationFind files that have not been updated despite significant changes occurring in the related code.
- 3Audit documentation completenessCheck if required documentation sections are missing based on the detected technology stack.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the docs-check skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the docs-check skill in Plugin
/plugin marketplace add mgiovani/cc-arsenal /plugin install cc-arsenal@cc-arsenal-marketplace
Install the docs-check skill in Claude Code
~/.claude/skills/docs-check/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-check ~/.claude/skills/docs-checkInstall the docs-check skill in Claude Code (project)
.claude/skills/docs-check/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-check .claude/skills/docs-checkInstall the docs-check skill in Codex
~/.agents/skills/docs-check/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-check ~/.agents/skills/docs-checkInstall the docs-check skill in Gemini CLI
~/.gemini/skills/docs-check/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-check ~/.gemini/skills/docs-checkInstall the docs-check skill in Claude.ai
npx degit mgiovani/cc-arsenal/skills/docs-check docs-check && zip -r docs-check.zip docs-check # claude.ai → Customize → Skills → + → Create skill → Upload a skill → docs-check.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablemgiovani/cc-arsenal/skills/docs-check is public and reachablegithub.com/mgiovani/cc-arsenal/tree/HEAD/skills/docs-check ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-28github.com/mgiovani/cc-arsenal/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-check/S ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-check/S ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-check/S ↗Finding
SKILL.md
View on GitHubCheck Documentation Quality
Audit documentation freshness, completeness, and quality against the current codebase state. Read-only: never edit or write to any doc file.
Anti-hallucination detection
This skill exists to catch docs that lie. For every claim in a doc, verify it against the actual codebase rather than trusting the doc text:
- Cross-reference claims: component/service names, described relationships
- Verify counts: if a doc says "5 services", count the actual services
- Check file references: confirm every referenced path exists
- Validate diagrams: every Mermaid entity must exist in real code
Workflow
Phase 1: Scan docs/
- Glob all documentation files (
docs/,docs/adr/,docs/rfc/, top-levelREADME.md,CONTRIBUTING.md). - Infer focus categories from the filenames actually present: don't assume a fixed set. A repo with
docs/data-model.mdgets a "data" category; one withdocs/deployment.mdanddocs/docker-compose.ymldocs gets "infrastructure"; group whatever's there under a name that matches its content. If the user names a focus that doesn't match anything found, say so and list the categories that do exist instead of silently no-op'ing. - Detect tech stack, database presence, deployment configs, and project type from the codebase (package files, Dockerfiles, etc.) to know what documentation should exist.
Phase 2: Parse arguments
Extract an optional focus keyword from the invocation and match it against the categories found in Phase 1. No argument means check everything found.
Phase 3: Verify claims against the codebase
For a small doc set (a handful of files, or a one-shot check like "does this file exist"), verify directly inline with Read/Grep/Glob/git: spawning a subagent for a single lookup adds latency for no benefit.
For a large multi-doc audit (a full docs/ tree, many ADRs, cross-referencing several files against the codebase), spawn one Explore subagent per document or logical section so each verifies its claims independently. Where no Task tool is available, fall back to processing each document sequentially inline instead: same verification steps, one document at a time, no parallelism. See references/verification-patterns.md for section-level verification patterns and bash commands.
Verification categories: component/service names, numeric counts, diagram entities, file/path references, technology claims (against package files), relationship claims.
Phase 4: Validation checks
Relevance: which docs are relevant given the detected stack; what's missing for detected technologies.
Freshness: compare each doc's last-modified date (git log) against related code changes. A doc untouched since before a significant change to the code it describes is stale.
Completeness: required sections present, no unreplaced {{PLACEHOLDER}} values, diagrams present where expected.
Quality: valid Mermaid syntax, no broken internal links, no empty sections.
Check Mermaid by rendering it. Needs mmdc: install with npm i -g @mermaid-js/mermaid-cli, or run it ad hoc by defining mmdc() { npx -y -p @mermaid-js/mermaid-cli mmdc "$@"; } first. If Chromium refuses to launch in a sandbox, add -p with a puppeteer config of {"args":["--no-sandbox"]}. Run this once over every doc found in Phase 1 (nothing it writes lands in the repo):
d=$(mktemp -d)
for md in $(find docs -name '*.md'); do
awk -v out="$d/${md//\//__}" '/^```mermaid/{f=out "-" ++n ".mmd"; next} /^```/{f=""} f{print > f}' "$md"
done
for f in "$d"/*.mmd; do mmdc -q -i "$f" -o "${f%.mmd}.svg" || echo "FAIL $f"; done
Each FAIL <name>-N.mmd is an invalid diagram: report the doc and the Nth mermaid block as a finding with the parser error, and never edit the doc. Run it once, with no fix loop. If mmdc can't be installed, say so in the report and review the syntax by eye, marking those results unverified.
See references/verification-patterns.md for the exact commands.
Phase 5: Rate each document
Skip numeric scoring: a 0-100 breakdown per doc implies precision this check doesn't have. Give each document one coarse rating instead:
- Good: current, complete, no broken links or invalid diagrams
- Stale: accurate but outdated (freshness or completeness gaps, no false claims)
- Broken: contains hallucinations, broken links, or invalid Mermaid syntax
- Missing: expected given the detected stack but doesn't exist
See references/scoring-criteria.md for the full rubric per rating.
Phase 6: Generate report
- Status summary with counts per rating
- Documents grouped by rating (Good / Stale / Broken / Missing)
- Hallucination Report: claims that don't match reality, with evidence
- Quality issues with specific file:line locations
- Actionable recommendations naming a specific follow-up command (docs-update, docs-diagram) and why
Output Format
Status Summary
Documentation Health Report
Good (3 docs):
docs/architecture.md
docs/onboarding.md
docs/adr/ (5 records)
Stale (2 docs):
docs/data-model.md — last updated 2025-03-01, schema changed 2025-06-15
docs/deployment.md — references removed staging environment
Broken (1 doc):
docs/architecture.md — Hallucination: claims "6 microservices", 3 found
Missing (1 doc, expected for detected stack):
docs/security.md — auth code present, no security doc
Hallucination Report
Hallucinations Detected:
docs/architecture.md:
- Line 45: Claims "6 microservices" but only 3 found
Verified with: find . -name "*service*" -type d | wc -l -> 3
- Line 78: References "AuthService" which doesn't exist
Verified with: grep -r "class AuthService" . -> no results
Recommendations Format
Priority Recommendations:
1. HIGH: docs/architecture.md claims 6 microservices, only 3 exist
Command: docs-update architecture
Reason: hallucinated count, misleads new engineers
2. MEDIUM: docs/data-model.md has 2 unreplaced {{PLACEHOLDER}} values
Command: docs-update data-model
Reason: incomplete since scaffolding
3. LOW: docs/security.md missing, auth module exists
Command: docs-diagram security or docs-init security
Reason: no security documentation for an app with auth
Usage Examples
docs-check # check everything found in docs/
docs-check core # focus on whatever category maps to "core" in this repo
docs-check focus on database documentation
Important Notes
- Non-destructive: only reads, never modifies documentation.
- Every number reported (counts, dates, "N days stale") must come from a command actually run in this session: never estimate or infer a count without running find/grep/git for it.
- Recommends
docs-updateordocs-diagramas the fix: this skill only reports.
When to Run
- Before onboarding new team members
- During documentation reviews
- After major refactoring
- As part of a pre-release checklist
- When documentation feels stale
Additional Resources
- references/verification-patterns.md: load when running Phase 3/4 verification, for exact bash/grep patterns and the subagent prompt templates
- references/scoring-criteria.md: load when assigning Phase 5 ratings, for the full Good/Stale/Broken/Missing rubric
Files in this skill
5docs-check skill questions
How do I install the docs-check skill in Claude Code?
Run npx degit mgiovani/cc-arsenal/skills/docs-check ~/.claude/skills/docs-check. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the docs-check skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Does this tool edit my documentation files?
No, this is a read-only audit tool that only reports findings and never modifies files.
How does the tool handle Mermaid diagrams?
It attempts to validate Mermaid syntax by rendering it using the mermaid-cli (mmdc); if it cannot be installed, it performs a visual syntax review.