System Prompts in Markdown: Sections, Examples, and Reuse

Writing a system prompt in Markdown gives it readable structure: headers for sections, lists for rules, code fences for examples. Most current large language models parse Markdown formatting in system prompts and use it as structure, even when the interface does not render it visually. Tools like fenbs keep approved system prompt files alongside the Decisions and rules that explain why each version was written, so the next person can start from the current approved version and understand its history.

The main constraint is that Markdown only helps if the interface you use passes the text to the model. Some product interfaces strip or transform the system prompt. Test before you rely on it.

What Markdown adds to a system prompt

A plain-text system prompt with six rules written as consecutive paragraphs is hard to scan and easy to contradict. A Markdown prompt with a ## Rules header followed by a numbered list is easier to read, easier to edit, and easier for the model to parse as a distinct section.

Markdown headers (## and ###) work as section labels. A model that encounters ## Output format followed by formatting instructions treats that section differently from ## Background followed by context. This mirrors how XML tags work for the same purpose; the choice between Markdown and XML usually comes down to which is more readable for the author. For system prompt XML, that article covers when XML is the stronger choice.

Basic structure and sections

A well-organized Markdown system prompt typically has three to five sections. Start with the persona or role, follow with the rules, and end with the output format. Add a background section if the model needs context to do its job correctly.

## Role
You are a research assistant for a US law firm. You help attorneys prepare research memos.

## Rules
1. Answer only questions related to US law and legal research.
2. Cite primary sources: statutes, regulations, and case law by full citation.
3. Do not state legal conclusions. Present the research and note that the reader should consult counsel.
4. If you cannot find a reliable primary source, say so rather than guessing.

## Output format
- Start with a one-sentence summary of the answer.
- Follow with cited supporting points.
- End with "Note: This is research only, not legal advice."

Keep sections short. A header with ten bullet points is harder to follow than two focused sections of five. If a section grows beyond what can be read in thirty seconds, split it.

Which interfaces support Markdown in system prompts

When you call the API directly (OpenAI, Anthropic, Google, xAI), the system message is plain text. You can write Markdown in it; the model parses the formatting as structure. The API does not render it as HTML -- you see the raw Markdown in your code.

In Claude Code, the AGENTS.md and CLAUDE.md files are Markdown system prompt files. Claude reads them as instructions, and the headers and lists are part of the structure. Cursor reads .cursorrules in a similar way. These tools were designed around Markdown instruction files.

In some product interfaces, the system instructions field renders Markdown as formatted text when you are writing it, but sends it to the model as the raw Markdown string. In others, the interface strips Markdown before sending. Test in the Playground or with a direct API call to see exactly what the model receives. The agents md vs system prompt article compares file-based and inline system prompts directly.

Loading a Markdown prompt from a file

Storing a system prompt in a .md file has practical advantages: version control, code review, and a clear history of changes. When you want to use the file in an API call, read the file and pass its contents as the system message string.

import anthropic
from pathlib import Path

system_prompt = Path("prompts/research_assistant.md").read_text()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=system_prompt,
    messages=[{"role": "user", "content": "What are the current FTC rules on endorsements?"}]
)

Keeping prompt files in version control alongside the code that uses them means every change to the prompt is tracked, reviewable, and attributable. You can see when a rule changed, who changed it, and what it said before.

Markdown vs. XML for structuring system prompts

Markdown and XML both add structure to a system prompt; the choice depends on what the structure needs to do. Markdown is better for human readability: a developer editing a .md file in a code editor can scan and update it quickly. XML tags are better when you need to isolate sections precisely -- especially when mixing instructions with user-provided data. Claude's documentation recommends XML for prompts that include external content because the tags make the boundary explicit.

In practice, many teams use Markdown for the base instruction file and XML within individual sections when a particular section needs strict boundaries. Say your prompt includes a section that passes a document into the model: that document goes in an XML tag even if the rest of the prompt is Markdown. This gives you the readability of Markdown for the parts you edit often and the precision of XML for the parts where boundaries matter most.

When Markdown adds no benefit

Markdown does not help when the system prompt is two sentences. Headers and lists add noise to a short instruction that works fine as a single paragraph. If you are writing a persona prompt like "You are a helpful cooking assistant. Answer questions about recipes and kitchen techniques," Markdown structure is unnecessary overhead.

Markdown also does not help when the interface strips it before sending. Verify what the model actually receives before investing time in Markdown structure.

How to do this with fenbs

1. Create a free account. Start a personal kanban board for your prompt work.
2. Add a task for the Markdown system prompt you are building. In the plan, list the sections and the purpose of each.
3. Draft the prompt in a .md file, commit it to version control, and test it with the API.
4. When you finalize a version, save the prompt text as a Skill in fenbs. Link it to the version control commit.
5. When a rule changes, record the reason as a Decision in fenbs -- not just what changed, but why. Link the Decision to the Skill so the next reader can find both.

Related: system prompt examples has complete prompts to study and adapt. Prompt engineering covers the general principles. For coding tools that use Markdown instruction files natively, the agents md vs system prompt comparison explains the options.