guide-lint

Audits and normalizes design system guide markdown files against a structural checklist.

Updated Jun 17, 2026
One-click install
npx skills add https://github.com/RickOBrian/aid --skill guide-lint-rickobrian
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: guide-lint
Source: https://github.com/RickOBrian/aid/tree/main/skills/guide-lint
Command: npx skills add https://github.com/RickOBrian/aid --skill guide-lint-rickobrian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Design system documentation files drift out of sync over time: inconsistent frontmatter field order, missing version metadata, unnumbered sections, and misaligned tables make guides hard to maintain. This Skill audits every *-guide.md file against a fixed checklist and normalizes deviations automatically. ## Core Features & Use Cases - Checklist-Based Audit: Validates frontmatter field order, semver versioning, heading structure, status lines, table alignment, token notation, and code block language tags. - Safe Normalization: Fixes only structural and formatting issues while strictly preserving guide content, token examples, and existing changelog entries. - Versioned Fixes with Commits: Applies a patch version bump, prepends a changelog entry, and creates one commit per fixed file. - Use Case: Run it before a design system release to verify all guides in skills/_shared/ follow the reference structure, then auto-fix violations with --auto mode. ## Quick Start Audit all guide files in skills/_shared/ and show me a report of any structural inconsistencies.

Frequently Asked Questions about guide-lint

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

FAQPage Schema
How do I lint markdown documentation files for structure?

Run the audit against your guide files to check frontmatter field order, heading numbering, status lines, and table alignment. The output is a per-file report table listing each checklist item as passed or failed, plus a summary of errors and warnings.

How to automatically fix markdown frontmatter and formatting issues?

Use the --auto mode to fix all detected violations without confirmation. Fixes are limited to structural items: field ordering, version bumps, changelog entries, and table alignment, while guide content and examples remain untouched.

Can I preview markdown lint fixes before applying them?

Yes, run with --dry-run to generate only the discrepancy report without modifying files or creating commits. This lets you review every violation and decide which files to fix interactively afterward.

Does markdown linting modify the actual guide content?

No, content inside sections, token examples, existing changelog entries, and table data are explicitly protected. Only structural elements like frontmatter order, heading format, and table whitespace alignment are normalized.

What are the limitations of checklist-based markdown linting?

It validates structure and formatting conventions but does not check factual accuracy, broken links, or content quality. Files must follow the expected guide conventions, and each fix requires a separate commit rather than a batch commit.