writing-ai-docs

AI-ready markdown documentation requires standardized frontmatter fields like title, description, type, created, and lastUpdated, along with strict heading hierarchy and explicit prerequisites. This Skill validates those structural rules so AI tools can parse and retrieve content reliably.

Required frontmatter fields for AI-friendly documentation include title, description, type, created, and lastUpdated. This Skill enforces these mandatory fields alongside optional discovery fields to ensure consistent metadata for AI parsing and retrieval.

You validate markdown files by running linting scripts that check required frontmatter, enforce one H1 per file, verify strict heading hierarchy, and report missing dependencies and references. This Skill scaffolds, validates, and lints files to fix structural issues.

Yes, this Skill validates existing markdown files across API, guide, tutorial, reference, concept, and troubleshooting contexts. It checks frontmatter compliance and structural governance to ensure your current documentation meets AI-ready standards.

Yes, pyyaml is required because frontmatter validation depends on parsing YAML metadata blocks in markdown files. This Skill uses pyyaml to read and validate required frontmatter fields like title, description, type, created, and lastUpdated.

Structural rules for AI-ready markdown include enforcing exactly one H1, maintaining strict heading hierarchy without skipping levels, writing self-contained sections, and using explicit language for AI chunking. This Skill validates all these constraints.