name: documentation-formatting description: Validate and format Markdown documentation structure. Use when Codex needs to check or fix heading numbering, prose wrap, table formatting, spacing, Markdown links, or other deterministic documentation formatting issues without doing broader documentation-content work.

Documentation Formatting

Use this skill for deterministic Markdown structure and validation.

This skill owns:

Do not use this skill to decide documentation topology or canonical topic ownership. Use the documentation-topology skill for that.

Run the bundled formatter in check mode first:

Use the narrowest flags that match the requested change:

Show all formatter drift and warnings to the user before any write action.

When --headings or --all are used with --check, review any warnings about missing or mis-numbered headings before asking to write.

Use these helpers before manual inspection when relevant:

Prefer validator output over manual scanning for structural issues.

Only after the user approves, run:

Only use the bundled formatter at scripts/format_markdown.py.
Do not substitute repository-local or third-party formatters unless the user explicitly asks.
Preserve fenced code blocks.
Do not wrap tables as prose.
Warn about wide table rows instead of force-wrapping them.
Keep heading numbering deterministic and hierarchical.

Prefer JSON output from validator scripts.

Exit codes:

This sub-skill includes local bundled scripts:

Use these local scripts instead of reaching outside the skill folder.