Proactive documentation quality assurance - validate frontmatter, links, READMEs, and changelogs
Proactively validates documentation quality by checking frontmatter, internal links, README completeness, and changelog compliance. Use it monthly or before major commits to catch broken links, missing metadata, and structural issues before they become problems.
/plugin marketplace add gaurangrshah/gsc-plugins/plugin install docs@gsc-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Purpose: Proactive documentation quality assurance and compliance checking
Philosophy: Catch documentation issues early, maintain quality standards, ensure queryability.
# Required
DOCS_ROOT="${DOCS_ROOT:-~/docs}"
KNOWLEDGE_BASE="${KNOWLEDGE_BASE:-~/.claude/knowledge}"
# Optional
WORKLOG_DB="${WORKLOG_DB:-}" # Log validation results to worklog
DOCS_QUERY_SCRIPT="${DOCS_QUERY_SCRIPT:-}" # Path to query-docs.sh or equivalent
Monthly Hygiene:
Before Major Commits:
After Major Doc Changes:
Proactive Quality Checks:
Checks:
title, type, createdtype values: decision, learning, guide, reference, changelog, environmentstatus values if present: active, deprecated, supersededReports:
Checks:
[text](path) links point to existing filesReports:
Checks:
Reports:
Checks:
Reports:
Checks:
Reports:
# Scan primary documentation
cd $DOCS_ROOT
find . -type f -name "*.md" | grep -v archive/
For each markdown file:
--- delimiters)For each markdown file:
[text](path) patternsFor each subdirectory:
For each README:
Create validation report in /tmp/docs-validation-YYYY-MM-DD.md:
# Documentation Validation Report
**Date:** YYYY-MM-DD HH:MM
**Scope:** $DOCS_ROOT
**Files Checked:** N
**Issues Found:** N
## Summary
- ❌ Critical: N (must fix)
- ⚠️ Warning: N (should fix)
- ℹ️ Info: N (consider fixing)
## Critical Issues
### Missing Frontmatter
- `path/to/file.md` - No frontmatter block found
### Broken Links
- `path/to/file.md:42` - Link to `missing.md` (file doesn't exist)
## Warnings
### Incomplete Frontmatter
- `path/to/file.md` - Missing required field: `created`
### Orphaned Files
- `security/old-config.md` - Not referenced in security/README.md
## Info
### Potential Improvements
- Consider adding `tags` field to improve queryability
- README could reference additional files
## Recommended Actions
1. Fix critical issues first (broken links, missing frontmatter)
2. Address warnings (incomplete frontmatter, orphaned files)
3. Consider info items for next documentation pass
## Files Validated
- $DOCS_ROOT/*.md (N files)
- $DOCS_ROOT/security/*.md (N files)
- $DOCS_ROOT/guides/*.md (N files)
- ...
---
title: "Brief descriptive title"
type: decision|learning|guide|reference|changelog|environment
created: YYYY-MM-DD
---
updated: YYYY-MM-DD
tags: [tag1, tag2, tag3]
status: active|deprecated|superseded
category: "Primary category"
related: [path/to/doc.md]
commit: abc1234
environment: system-name
| Type | Use Case |
|---|---|
decision | Architectural or operational decisions |
learning | Lessons learned from incidents or tasks |
guide | How-to documentation and procedures |
reference | Reference documentation and indexes |
changelog | Change history and logs |
environment | Environment-specific documentation |
| Status | Meaning |
|---|---|
active | Currently in use |
deprecated | No longer recommended, but still referenced |
superseded | Replaced by newer documentation |
For fast checks before commits:
Quick Mode Checks:
Usage:
# Quick validation (1-2 minutes)
/skill docs-validator --quick
# Full validation (5-10 minutes)
/skill docs-validator
# Specific directory
/skill docs-validator --path $DOCS_ROOT/security
When $DOCS_QUERY_SCRIPT is set, validation ensures all documents are queryable:
# After validation, these queries should work
$DOCS_QUERY_SCRIPT --type guide
$DOCS_QUERY_SCRIPT --tag security
$DOCS_QUERY_SCRIPT --status active
Validation complements docs-manager:
Workflow:
Validation can be part of baseline checks:
Issue: File has no YAML frontmatter
Fix:
# Add frontmatter to file
cat > /tmp/frontmatter.txt <<'EOF'
---
title: "File Title"
type: guide
created: 2025-01-15
---
EOF
# Prepend to file
cat /tmp/frontmatter.txt original.md > new.md
mv new.md original.md
Issue: [text](missing.md) points to non-existent file
Fix:
Issue: File exists but not referenced in README
Fix:
# In README.md, add reference:
**[File Title](filename.md)** - Brief description
**Contents:**
- Key point 1
- Key point 2
Issue: Changelog entry doesn't follow format
Fix:
# Correct format:
### YYYY-MM-DD - Title
**Changed:** What changed
**Why:** Reason for change
**Impact:** Effect of change
**See also:** Related documentation
When $WORKLOG_DB is set, log validation results:
sqlite3 "$WORKLOG_DB" "INSERT INTO entries
(agent, task_type, title, details, outcome, tags) VALUES (
'$(hostname)',
'validation',
'Documentation validation - $DOCS_ROOT',
'Checked N files, found N issues (N critical, N warning)',
'Validation complete - see /tmp/docs-validation-YYYY-MM-DD.md',
'docs,validation,quality'
);"
Could validate before git commits:
#!/bin/bash
# .git/hooks/pre-commit
/skill docs-validator --quick
Could be automated to run monthly:
# Add to crontab (if desired)
0 9 1 * * /skill docs-validator > /tmp/monthly-validation.log
If documentation repo has CI:
User: "Run docs validation"
Skill Actions:
Output:
📋 Documentation Validation Report
Checked: 42 files
Issues: 3 critical, 5 warnings, 2 info
❌ Critical Issues:
- security/new-policy.md: Missing frontmatter
- guides/README.md: Broken link to old-guide.md
- services/deploy.md: Missing required field 'created'
⚠️ Warnings:
- 5 files not referenced in READMEs
ℹ️ Info:
- Consider adding tags to 2 files for better queryability
Full report: /tmp/docs-validation-YYYY-MM-DD.md
Fix critical issues? (y/n)
Good documentation system:
After validation:
When to run docs-validator:
How to use:
# Full validation
/skill docs-validator
# Quick check
/skill docs-validator --quick
# Specific directory
/skill docs-validator --path $DOCS_ROOT/security
Remember: Validation is proactive. Catch issues before they become problems.
Skill Version: 2.0.0 Philosophy: Proactive quality assurance. Early detection. Maintainable documentation.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.