Initial commit

skills/doc-validator/REFERENCE.md

@@ -0,0 +1,85 @@
+# Documentation Validator Reference
+
+Detailed validation rules and patterns for documentation quality assurance.
+
+## Markdown Linting Rules
+
+### Headings
+- Must start with `#` (H1) for document title
+- No skipping heading levels (no H1 → H3)
+- Each heading should be unique
+- Use sentence case for headings
+
+### Code Blocks
+- Always specify language: ` ```bash `, ` ```python `, etc.
+- Code should be runnable (or marked as pseudocode)
+- Avoid long lines (max 80-100 characters)
+
+### Links
+- Use relative links for internal files
+- Check external links are accessible
+- Use descriptive link text (not "click here")
+
+### Lists
+- Consistent marker style (- vs * vs +)
+- Proper indentation for nested lists
+- Complete sentences with periods
+
+## Version Validation
+
+Check version consistency across:
+- package.json (`version` field)
+- pyproject.toml (`version` field)
+- README.md (version badges, installation commands)
+- CHANGELOG.md (latest version entry)
+- setup.py (`version` field)
+
+## CLI Command Validation
+
+For each command mentioned in docs:
+1. Search for actual implementation
+2. Verify flags/arguments match
+3. Check help text matches documentation
+4. Validate examples are correct
+
+Example check:
+```bash
+# Documentation says:
+make install MODULE=foo
+
+# Verify:
+grep -r "CLAUDE_DIR" Makefile  # Check parameter exists
+make help                       # Verify command listed
+```
+
+## Common Issues
+
+### Missing Installation Steps
+- No prerequisites listed
+- No dependency installation
+- Missing system requirements
+- No version requirements
+
+### Broken Examples
+- Code examples with syntax errors
+- Commands that don't exist
+- File paths that don't exist
+- Outdated package names
+
+### Inconsistent Terminology
+- "repo" vs "repository"
+- "module" vs "package"
+- "CLI" vs "command-line tool"
+
+Pick one term and use it throughout.
+
+## Auto-Fix Patterns
+
+Some issues can be auto-fixed:
+- Add missing code block language hints
+- Fix heading hierarchy
+- Normalize list markers
+- Add table of contents
+- Update version numbers
+
+Ask user before applying fixes.

skills/doc-validator/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: doc-validator
+description: Validate documentation files for completeness, accuracy, and consistency with the codebase. Use when user mentions "check documentation", "validate docs", "is the README up to date?", requests documentation review, says "docs are wrong" or "fix the docs", or is working on documentation improvements. Covers README files, API docs, CHANGELOG, and any markdown documentation.
+---
+
+# Documentation Validator
+
+## Validation Checks
+
+### 1. Completeness
+- [ ] Installation instructions present
+- [ ] Usage examples provided
+- [ ] API reference complete (if applicable)
+- [ ] Troubleshooting section exists
+- [ ] Contributing guidelines (if open source)
+
+### 2. Accuracy
+- [ ] Code examples are runnable
+- [ ] Commands match actual CLI
+- [ ] File paths exist
+- [ ] Version numbers match package.json/pyproject.toml
+- [ ] Links are not broken
+
+### 3. Consistency
+- [ ] Terminology is consistent
+- [ ] Code style in examples matches project
+- [ ] Formatting is uniform
+- [ ] Table of contents matches headings
+
+### 4. Quality
+- [ ] No spelling/grammar errors
+- [ ] Clear and concise language
+- [ ] Proper markdown formatting
+- [ ] Code blocks have language hints
+
+## Process
+
+1. **Find documentation files**
+   ```bash
+   find . -name "*.md" -o -name "*.rst"
+   ```
+
+2. **Read and analyze**
+   - Check structure (headings, sections)
+   - Verify code examples
+   - Validate links and references
+
+3. **Cross-reference with code**
+   - Compare CLI commands with actual implementation
+   - Verify file paths exist
+   - Check version numbers
+
+4. **Report findings**
+   - List issues by category
+   - Suggest improvements
+   - Provide examples of fixes
+
+## Examples
+
+✅ **Good trigger**: "Check if our README is complete"
+✅ **Good trigger**: "Validate the API documentation"
+✅ **Good trigger**: "The docs mention /old-command but I don't see it in the code"
+
+❌ **Bad trigger**: "Write new documentation" (creation, not validation)
+❌ **Bad trigger**: "Fix typo in line 42" (too specific, not validation)
+
+## Supporting Files
+
+For detailed validation rules, see [REFERENCE.md](REFERENCE.md).