documentation-standards

Markdown documentation standards define formatting rules, writing style, and structural guidelines to ensure consistency. This Skill enforces language conventions, heading levels, indentation, emoji restrictions, and validates files using markdownlint-cli2 to eliminate ambiguity and improve readability across all project documents.

Apply two-space indentation, use consistent heading hierarchy, restrict emoji use, prefer Mermaid diagrams over external images, and maintain unified terminology throughout. Write in plain style, keep code separate from specifications, and prioritize conciseness to ensure clarity and maintainability.

Markdownlint-cli2 automatically validates Markdown files against predefined rules, catching common formatting errors and style violations before publication. It highlights inconsistencies in heading structure, list formatting, and spacing, ensuring your documentation adheres to team standards without manual review.

Yes. This Skill applies documentation standards during README authoring, technical specification creation, and any Markdown editing workflow. It ensures both file types follow consistent style, structure, and validation rules, making documentation accessible and maintainable for all team members.

Markdownlint identifies violations but does not automatically fix them unless explicitly requested. You review flagged issues—such as improper heading levels, indentation errors, or style deviations—and manually correct them to align with your project's documentation standards.

If your project targets Japanese audiences or uses Japanese as the primary language, these standards enforce plain-form Japanese style and language conventions. For English-only projects, focus on the structural guidelines—heading hierarchy, indentation, consistency—and markdownlint validation rules.