doc-validator

bodangren's avatarfrom bodangren

Use this skill to validate that Markdown files are in standard locations. Scans for .md files outside of predefined allowed directories and outputs warnings to prevent documentation sprawl. Triggers include "validate docs", "check markdown locations", or as part of quality checks.

⭐7stars🔀1forks📁View on GitHub🕐Updated Dec 6, 2025⬇️1downloads
[Developer Tools]

When & Why to Use This Skill

This Claude skill automates the validation of Markdown file locations within a repository to prevent documentation sprawl. By scanning for .md files outside authorized directories, it ensures a clean, organized project structure and enforces documentation standards during code reviews or CI/CD processes, making it an essential utility for maintaining repository health and technical documentation consistency.

Use Cases

  • CI/CD Pipeline Integration: Automatically trigger warnings or quality gate failures when documentation is placed in incorrect directories to maintain a clean repository.
  • Code Review Automation: Streamline the pull request review process by automatically flagging misplaced .md files, ensuring contributors adhere to project-specific directory conventions.
  • Repository Auditing: Conduct periodic scans of large, multi-contributor codebases to identify and relocate abandoned or disorganized documentation files.
  • Documentation Standards Enforcement: Help maintain a consistent documentation architecture across complex projects by enforcing predefined 'allowed' patterns for file placement.
namedoc-validator
descriptionUse this skill to validate that Markdown files are in standard locations. Scans for .md files outside of predefined allowed directories and outputs warnings to prevent documentation sprawl. Triggers include "validate docs", "check markdown locations", or as part of quality checks.
categoryproject

Doc Validator

Purpose

Scan the repository for Markdown files (.md) located outside of predefined, allowed directories. This skill helps prevent documentation sprawl and enforces a consistent repository structure by warning about .md files in non-standard locations.

When to Use

Use this skill in the following situations:

  • During code reviews to ensure documentation is properly organized
  • As part of CI/CD quality checks
  • Before merging changes that add new documentation
  • When auditing the repository for documentation compliance
  • Called automatically by other skills (issue-executor, change-integrator)

Prerequisites

  • Standard bash utilities (find, bash)
  • Project follows AgenticDev directory conventions

Workflow

Step 1: Run the Validator

Execute the validator script to scan for misplaced Markdown files:

bash skills/doc-validator/scripts/doc-validator.sh

Step 2: Review Warnings

The script outputs warnings for any .md files found in non-standard locations:

WARNING: Markdown file in non-standard location: ./src/notes.md
WARNING: Markdown file in non-standard location: ./scripts/temp-docs.md

Step 3: Take Action

For each warning:

  1. Determine if the file should exist: Is it temporary or abandoned?
  2. Move to proper location: Relocate to docs/ or appropriate skill directory
  3. Add to allowed patterns: If it's a legitimate exception (update the script)
  4. Remove the file: If it's no longer needed

Allowed Patterns

The validator considers these locations as standard and will not warn about them:

  • Root-level documentation: README.md, LICENSE, AGENTS.md, RETROSPECTIVE.md
  • Main docs directory: docs/**/*.md (all subdirectories)
  • Skill documentation:
    • skills/*/SKILL.md
    • skills/*/references/*.md
    • skills/*/examples/*.md
    • .claude/skills/*/SKILL.md
    • .claude/skills/*/references/*.md
    • .claude/skills/*/examples/*.md

Error Handling

False Positives

Symptom: The validator warns about a file that should be allowed

Solution:

  • Check if the file matches an allowed pattern
  • If it's a legitimate location not covered by current patterns, update doc-validator.sh
  • Add the new pattern to the ALLOWED_PATTERNS array

Script Not Finding Files

Symptom: The script runs but finds no files or fewer files than expected

Solution:

  • Verify you're running from the repository root
  • Check file permissions
  • Ensure .md files exist in the repository

Permission Denied

Symptom: Script cannot access certain directories

Solution:

  • Check directory permissions
  • Ensure the script is executable: chmod +x skills/doc-validator/scripts/doc-validator.sh

Notes

  • Non-destructive: The script only reports issues, it does not move or delete files
  • Excludes: Automatically skips .git/ and .agenticdev-backup-* directories
  • Integration: Designed to be called by other skills as part of quality checks
  • Extensible: Easy to add new allowed patterns by updating the script
  • CI-friendly: Returns parsable output suitable for automated checks