Markdown Compliance

Markdown Compliance Skill

This skill defines the strict standards for markdown files in this project, based on markdownlint rules (MD001-MD050+). All agents and tools MUST adhere to these rules when generating documentation, logs, or agent definitions.

1. Heading Rules (Structure)

• MD001 (Level 1): Header levels must increase by one level at a time.
  • Example: H1 -> H2 -> H3 (Correct). H1 -> H3 (Incorrect).
• MD002 (First Header): The first header in the file should be a top-level header (H1).
• MD003 (Style): Use ATX style (# Heading) exclusively. Do NOT use Setext style (Heading\n---).
• MD018 (Space after hash): Always put a space after the hash characters. (# Title, not #Title).
• MD019 (No multiple spaces): Only one space after hash.
• MD022 (Blanks around): Headings must be surrounded by a blank line (one before, one after).
  • Exception: The first line of the file (if H1) doesn't need a blank line before it.
• MD023 (Start of line): Headings must start at the beginning of the line (no indentation).
• MD024 (Duplicate): Avoid duplicate headings in the same document level if possible.
• MD025 (Single H1): Document must have exactly one H1 header.
• MD036 (Emphasis): Do not use emphasis (bold/italic) as a substitute for a heading.
• MD041 (First Line): The file should start with an H1 heading (unless it has frontmatter, then H1 comes after).

2. List Rules (Structure & Spacing)

• MD004 (Unordered Style): Use hyphens (-) for unordered lists.
• MD005 (Inconsistent Indent): Consistency is key.
• MD006 (Start Bullet): Top-level lists must start at the beginning of the line.
• MD007 (Indentation): Use 2 spaces for indentation of sub-lists.
• MD029 (Ordered Style): Use sequential numbering (1., 2., 3.) for clarity, or 1. for all items if lazy numbering is preferred (Agent preference: Sequential).
• MD030 (Marker Spacing): Strictly 1 space after the list marker.
  • Correct: - Item
  • Incorrect: - Item
• MD032 (Blanks around): Lists must be separated from other content (headers, paragraphs) by blank lines.

3. Code Block Rules

• MD014 (Dollar Sign): Do not use $ output for shell commands unless showing output separate from command.
• MD031 (Blanks around): Fenced code blocks must be surrounded by blank lines.
  • Critical constraint: If a code block is nested in a list, the blank lines must respect the list's scope.
• MD040 (Language): Fenced code blocks must have a language specified (e.g., bash, python, markdown).
  • Exception: If the language cannot be detected or is not applicable, wrap the code block with <!-- markdownlint-disable MD040 --> and <!-- markdownlint-enable MD040 --> to suppress the warning.
• MD046 (Style): Use Fenced code blocks (```) exclusively. Do NOT use indented code blocks.
• MD048 (Style): Use backticks (`) for code fences. Do not use tildes (~).

4. Line & Character Rules

• MD009 (Trailing Spaces): No trailing spaces at the end of lines.
• MD010 (Hard Tabs): Do not use hard tabs. Use spaces.
• MD012 (Multiple Blanks): No consecutive blank lines (max 1).
• MD034 (Bare URLs): URLs should be enclosed in angle brackets (<http://...>) or formatted as links [text](url) properly.
• MD037 (Space in emphasis): No spaces inside emphasis markers.
  • Correct: **Text**
  • Incorrect: ** Text **
• MD039 (Space in links): No spaces inside link text brackets. [ Text ] -> [Text].
• MD047 (Final newline): Files should end with a single newline character.

5. HTML & Frontmatter

• MD033 (Inline HTML): Avoid raw HTML if possible.
  • Exception: <br> is sometimes acceptable for line breaks in tables.
  • Agent Exception: <use_mcp_tool> or similar XML-like tags used for agent logic are NOT standard HTML and should be wrapped in code blocks or handled carefully to not break markdown parsing.
• Frontmatter: Must be at the very top of the file, delimited by ---.
• Spacing after Frontmatter: Ensure a blank line exists between the closing --- and the first H1.

6. Implementation Checklist for Agents

When generating a file, run this mental check:

1. H1 Present? Is it the first real line?
2. Blanks Everywhere? Before/after headers? Before/after lists? Before/after code blocks?
3. Indentation? Are sub-lists indented by exactly 2 spaces?
4. Markers? Is there exactly one space after - or 1.?
5. Fences? Are all code blocks fenced with a language?

Example of Compliant Markdown

---
name: example-agent
---

# Title of the Document

This is a paragraph description.

## Section Header (MD022 applied)

- List item 1 (MD004: dash)
- List item 2
  - Sub-item (MD007: 2 spaces)

### Code Section

Here is a script:

```bash
echo "Hello World"

End of document.