Markdown Header Format
The second most common envelope format (~29%, ~15 tools). Uses ## heading hierarchy to structure instructions. Benefits include human readability, native alignment with LLM training data (documentation format), and lower token overhead than XML.
Structure (confidence: high)
## Role
You are...
## Tools
### search
...
## Rules
- Never...Variants (confidence: high)
- Flat headers (Cursor, Windsurf): All
##, no nesting. Easier to scan. - Deeply nested (Claude Code, Warp): 3-4 levels (
##>###>####). - Numbered sections (Gemini CLI):
## 1. Role,## 2. Tools. - Bulleted sub-sections (Lovable, Z.ai): Sparse
###use, relies on bullet hierarchy.
Format Selection Trade-offs (confidence: high)
| Format | Token Efficiency | LLM Compliance | Human Editability | Machine Parseability |
|---|---|---|---|---|
| XML Envelope | Medium | High | Medium | High |
| Markdown Headers | High | High | High | Low |
Implications: Markdown headers are the preferred format for developer-facing tools because humans can read, edit, and reason about them with minimal friction. The trade-off is lower machine parseability compared to XML, but for tools where prompt transparency matters (Cursor, Claude Code, Warp), this is acceptable. Markdown’s lower token overhead also matters for tools optimizing context window usage.
See also: xml-envelope-format, xml-vs-markdown-envelopes, format-interoperability
Sources
- [raw/prompts/articles/taxonomy-synthesis-2026-07-16.md]