Content Consistency Validator
Overview
Checks content for tone, terminology, formatting, and structural consistency across multiple documentation sources (websites, GitHub repos, local docs). Generates read-only discrepancy reports with severity-classified findings and actionable fix suggestions including file paths and line numbers.
Examples
- Pre-release audit: Before tagging a new version, run the validator to catch version mismatches between your README, docs site, and changelog — e.g., the website says v2.1.0 but the GitHub README still references v2.0.0.
- Post-rebrand check: After renaming a product or updating terminology (e.g., "plugin" to "extension"), validate that all docs, landing pages, and contributing guides use the new term consistently.
- Onboarding review: When a new contributor flags confusing docs, run a consistency check to surface contradictory feature claims, outdated contact info, or missing sections across your documentation sources.
Prerequisites
- Access to at least two content sources (website, GitHub repo, or local docs directory)
- WebFetch permissions configured for remote URLs (deployed sites, GitHub raw content)
- Local documentation stored in recognizable paths (
docs/,claudes-docs/,internal/)
Instructions
- Discover sources — scan for build directories (
dist/,build/,public/,out/,_site/), GitHub README/CONTRIBUTING files, and local doc folders:find. -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - Extract structured data from each source: version numbers, feature claims, product names, taglines, contact info, URLs, and technical requirements:
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - Verify extraction — confirm at least 3 data points per source. If a source returns empty, check the Error Handling table before continuing.
- Build comparison matrix pairing each source against every other (website vs GitHub, website vs local docs, GitHub vs local docs):
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - Classify discrepancies by severity:
- Critical: conflicting version numbers, contradictory feature lists, mismatched contact info, broken cross-references - Warning: inconsistent terminology (e.g., "plugin" vs "extension"), missing information in one source, outdated dates - Informational: stylistic differences, platform-specific wording, differing detail levels
- Apply trust priority: website (most authoritative) > GitHub (developer-facing) > local docs (internal use).
- Generate report as Markdown with: executive summary, per-pair comparison tables, terminology consistency matrix, and prioritized action items with file paths and line numbers.
- Save to
consistency-reports/YYYY-MM-DD-HH-MM-SS.md.
Report Format
# Consistency Report — YYYY-MM-DD
## Executive Summary
| Severity | Count |
|----------|-------|
| Critical | 2 |
| Warning | 5 |
| Info | 3 |
## Website vs GitHub
| Field | Website | GitHub | Severity |
|-------------|---------------|---------------|----------|
| Version | v2.1.0 | v2.0.0 | Critical |
| Feature X | listed | missing | Warning |
## Action Items
1. **Critical** — Update `README.md:14` version from v2.0.0 → v2.1.0
2. **Warning** — Add "Feature X" to `README.md` feature listOutput
The skill produces a timestamped Markdown report saved to consistency-reports/YYYY-MM-DD-HH-MM-SS.md containing:
- Executive summary: Severity counts (Critical/Warning/Info) at a glance
- Pair comparison tables: Field-by-field comparison between each source pair with severity classification
- Terminology matrix: Cross-source consistency check for product names, versions, and key terms
- Prioritized action items: Specific fixes with file paths and line numbers, ordered by severity
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Website content unreachable | URL returns 4xx/5xx or build dir missing | Verify site is deployed or run local build; check WebFetch permissions |
| GitHub API rate limit | Too many fetches in short window | Pause and retry after reset window; use authenticated requests |
| No documentation directory | Expected paths don't exist | Confirm working directory; specify doc path explicitly |
| Empty content extraction | Client-side rendering not visible to fetch | Use local build output directory instead of live URL |
| Diff command failure | File paths contain special characters | Quote all file paths passed to diff and grep |
Resources
- Content source discovery logic:
${CLAUDE_SKILL_DIR}/references/how-it-works.md - Trust priority and validation timing:
${CLAUDE_SKILL_DIR}/references/best-practices.md - Use-case walkthroughs:
${CLAUDE_SKILL_DIR}/references/example-use-cases.md