Markdown Standards

Provides: Portable Markdown formatting rules, a carve-out for skill files, and validation checks that avoid formatting-only churn.

Quick Reference

• Use ATX headings (#, ##, ###) with sentence-case, descriptive labels.
• Keep heading hierarchy ordered; do not skip levels.
• Do not hard-wrap prose mid-sentence. Keep a sentence or short paragraph on one line unless structure requires a break.
• Do not reflow paragraphs you did not otherwise change.
• Use fenced code blocks with language tags.
• Use descriptive link text; avoid raw URLs as link text where practical.
• Prefer lists over tables for prose-heavy content.
• Prefer Markdown over HTML unless Markdown cannot express the content.
• Avoid trailing whitespace.

Golden Rule: Optimize for readable diffs, not for a fixed column width

SKILL.md Exception

Skill files are agent context, not documents for human browsing. For any SKILL.md, prioritize trigger quality and context size over general document structure:

• Do not require an H1 matching the filename, a [TOC], or a closing ## See also.
• Keep SKILL.md compact and move conditional detail to references/.
• Put trigger guidance in the frontmatter description, not only in the body.
• Include only examples and validation that change agent behavior.

Apply the rest of this skill's formatting rules to skill files normally. Only the document-shape requirements are waived.

Layout

For regular documents:

• Start with one H1 and a short intro of one to three sentences.
• Use ## for major sections and ### for subsections. Keep heading names unique.
• Put supplemental links near the relevant text, or at the end under ## See also.
• Add [TOC] after the intro only when the hosting platform renders it.

For short operational documents, a predictable checklist often beats a full narrative.

Prose and Whitespace

Keep paragraphs semantic and let the editor or renderer wrap them. Fixed-width hard wraps create noisy diffs, because a one-word edit reflows every following line, and they split ideas across lines in ways that are awkward for both agents and reviewers to edit.

Never leave trailing whitespace. Use a single trailing backslash only where a literal line break is required, and sparingly.

Lists and Code

• Use ordered lists for sequences and bullets for unordered items.
• Use lazy numbering (1.) for long lists whose order may change.
• Indent nested list content consistently, four spaces inside list items.
• Use backticks for commands, paths, field names, and literals, and to escape text that would otherwise be parsed as Markdown.
• Specify the language immediately after the opening fence.
• When showing Markdown that itself contains code fences, use a longer outer fence or simplify the example.

1. Run the build

    ```bash
    npm run build
    ```

Links, Images, and Tables

• Give every link meaningful text. Never label a link "click here" or paste the raw URL as the text.
• Use reference-style definitions for long URLs, repeated links, and links inside table cells.
• Place reference definitions at the end of the section, or at the end of the document when shared.
• Keep internal links explicit; avoid ../ jumps across directories unless unavoidable.
• Add images only when they carry information prose cannot, such as an annotated screenshot, and always give meaningful alt text.
• Reserve tables for genuinely tabular data with consistent columns. Fall back to headings and bullet lists when the content is prose.

See the [style guide][style] for details.

[style]: https://google.github.io/styleguide/docguide/style.html

HTML

Stick to Markdown syntax. HTML reduces portability and often introduces validation issues. Use raw HTML only when Markdown cannot express the layout, and note why it was necessary.

Checklist

Before finishing Markdown changes:

• Headings are ordered, descriptive, in sentence case, and not duplicated
• Code fences open and close cleanly and carry language tags
• Fences inside list items are indented so the Markdown stays valid
• Links have descriptive text, with reference definitions for long or repeated URLs
• Prose is not hard-wrapped mid-sentence, and unchanged paragraphs were not reflowed
• No trailing whitespace was introduced
• Images are high-value and have alt text
• Tables hold tabular data, not prose
• Any HTML block is justified
• The document is no longer than its purpose requires
• For a SKILL.md, the document-shape requirements above were correctly waived

See also

• Load standards-documentation for content structure, audience, and what to document.
• Load standards-skill-authoring when the file being edited is a SKILL.md.