skills.rest
Reading-Advantage-Thailand
Reading-Advantage-ThailandOFFICIAL
Explore all skills by this author →
GitHub

doc-validator

Detects Markdown files located outside allowed repository directories and outputs warnings.

Updated Jul 13, 2024
Search Tags:#linting#documentation#markdown#validation#bash#repository structure#ci checks
One-click install
npx skills add https://github.com/Reading-Advantage-Thailand/codecamp-advantage --skill doc-validator-reading-advantage-thailand
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: doc-validator
Source: https://github.com/Reading-Advantage-Thailand/codecamp-advantage/tree/main/.claude/skills/doc-validator
Command: npx skills add https://github.com/Reading-Advantage-Thailand/codecamp-advantage --skill doc-validator-reading-advantage-thailand

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Documentation sprawl happens when Markdown files accumulate in random locations across a repository, making docs hard to find and maintain. This Skill scans the repository and warns about any .md files outside predefined standard locations. ## Core Features & Use Cases - Repository-wide scan: Finds all .md files and checks them against configurable allowed patterns covering root docs, docs/, and skill directories. - Non-destructive warnings: Only reports misplaced files without moving or deleting anything, safe for CI pipelines. - Extensible patterns: Add new allowed locations by updating the ALLOWED_PATTERNS array in the script. - Use Case: Run it during code review or before merging a pull request to catch a stray notes.md committed under src/ and relocate it to docs/. ## Quick Start Ask the AI to run the doc-validator script and report any Markdown files in non-standard locations.

Frequently Asked Questions about doc-validator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check for Markdown files in wrong locations in a repository?▼

Run the doc-validator.sh script from the repository root with bash. It scans all .md files, compares them against allowed patterns like docs/** and skills/*/SKILL.md, and prints a WARNING line for each file in a non-standard location.

How to enforce documentation structure in a CI pipeline?▼

Invoke the validator script as a CI step and parse its WARNING output lines. The script is non-destructive and returns parsable output, so you can fail the build or post comments when misplaced Markdown files are detected.

Which Markdown file locations does the validator allow by default?▼

Allowed locations include root-level README.md, LICENSE, AGENTS.md, and RETROSPECTIVE.md, everything under docs/, and SKILL.md, references, and examples files inside skills/ and .claude/skills/ directories.

Why does the validator warn about a file that should be allowed?▼

The file likely does not match any pattern in the ALLOWED_PATTERNS array. If the location is legitimate, edit doc-validator.sh and add a new glob pattern covering that path, then rerun the script.

Does the doc validator move or delete misplaced files?▼

No, the script is strictly non-destructive. It only prints warnings for files in non-standard locations, leaving all relocation or deletion decisions to the user.

Related Skills

Explore More Software Engineering Skills→
AINative-StudioAINative-Studio

file-placement

Validate Markdown and shell script placement against repository directory conventions.

Official
Intermediate
cipherstashcipherstash
17

Organizing Documentation

Audit project documentation and reorganize it into BUILD, FIX, UNDERSTAND, and LOOKUP categories.

Community
Basic
flext-shflext-sh

rules-docs

Validate markdown documentation for broken links, placeholders, and path consistency.

Official
Intermediate
frap129frap129
8

crafting-rules

Create and refine OpenCode rules with globs and keywords.

Community
Intermediate