doc-validator

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