skills.rest
Gamaroff
GamaroffCOMMUNITY
Explore all skills by this author →
Website𝕏@gamaroffGitHub

documentation-standards-validator

Validate documentation files against naming conventions, YAML frontmatter, and structural standards.

2|Updated Feb 14, 2026
Search Tags:#documentation#markdown#validation#standards#naming conventions#change log#frontmatter
One-click install
npx skills add https://github.com/Gamaroff/agent-skills --skill documentation-standards-validator-gamaroff
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-standards-validator
Source: https://github.com/Gamaroff/agent-skills/tree/main/skills/documentation-standards-validator
Command: npx skills add https://github.com/Gamaroff/agent-skills --skill documentation-standards-validator-gamaroff

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Teams maintaining PRDs, epics, and stories in Markdown often drift into inconsistent filenames, missing frontmatter fields, and malformed Change Log sections, making documents hard to discover and audit. This Skill defines precise mechanical checks so every document follows the same conventions. ## Core Features & Use Cases - Naming Convention Enforcement: Validates the epic.NUMBER.name.md and story.EPIC.STORY.name.md formats, requiring dots instead of underscores and self-named story subdirectories. - Frontmatter Validation: Checks required YAML fields for epics and stories, kebab-case status values, ISO dates, and OKF v0.1 conformance with severity grading (Critical for missing type, Important for missing description). - Change Log Auditing: Verifies the four-column Change Log table, heading format, row freshness against frontmatter updated, and exempts bug reports that use Status History instead. - Use Case: When reviewing a documentation PR, activate this Skill to audit every touched epic and story file for naming violations, missing frontmatter keys, and stale Change Logs before merging. ## Quick Start Ask the agent to validate the epic and story documents in your docs directory against the documentation standards and report any naming or frontmatter violations.

Frequently Asked Questions about documentation-standards-validator

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

FAQPage Schema
How do I validate epic and story file naming conventions?▼

Use dots to separate components and hyphens only within descriptive names, following the patterns epic.NUMBER.name.md and story.EPIC.STORY.name.md. Stories must also sit in self-named subdirectories inside the epic's stories folder, and all names must be lowercase.

What YAML frontmatter fields are required for a story document?▼

Required fields include epic, epic_number, story_number, title, type, description, tags, status, priority, story_type, risk_level, assignee, estimated_effort_hours, created, updated, and github_issue. Status values must be kebab-case such as ready-for-development, and dates must use ISO YYYY-MM-DD format.

Does this skill include a linter script to run the checks?▼

No, the skill ships no shared linter. It defines each check precisely enough for a consuming repository to implement as its own git hook, CI job, or script against its own documentation layout, since doc roots differ per repo.

What is the Change Log check and when is it enforced?▼

The Change Log check verifies a document carries a Change Log heading with exactly four columns (Date, Version, Description, Author), at least one dated row, and frontmatter updated no older than the newest row. It is gated by change-log.enabled in skills-config.yaml and graded per change-log.enforcement, defaulting to advisory.

Are bug reports required to have a Change Log section?▼

No, bug reports are exempt because they carry a Status History section instead, which has different columns (Date, Status, Changed By, Notes) suited to bug tracking. Do not flag a bug report for a missing Change Log or add one to it.

What happens when a document is missing the type frontmatter field?▼

A missing or empty type field is flagged as a Critical finding under OKF v0.1 conformance, since type is OKF's single hard requirement. A missing description is graded Important, while malformed tags or resource fields are only Optional findings.

Related Skills

Explore More Product & Management Skills→
sebc-devsebc-dev

epic-initializer

Create standardized epic directories and EPIC_TRACKING.md files.

Community
Basic
aoecosystemaoecosystem

approve-brief

Validates project briefs and gates pipeline from BRIEF_DRAFT to BRIEF_APPROVED.

Official
Advanced
weisbergweisberg
2

lira

Manage local YAML issue tickets with Jira and GitHub sync.

Community
Intermediate
opensquillaopensquilla
6.8k

meta-pre-commit-quality-gate

Runs ruff, mypy, and pytest in parallel over staged diffs and arbitrates a BLOCK or APPROVE verdict.

Official
Advanced