Writing markdown files for AI assistants

Builds on concepts from Introduction to Markdown.

Markdown files serve a dual purpose when working with AI coding assistants: they're human-readable documentation AND machine-parseable instructions. This tutorial explores the design considerations most users overlook.

The invisible audience problem

When you write a README.md, you think about human readers. When you write a .github/copilot-instructions.md, you're writing for an AI that will interpret your instructions. But here's what many users miss: the AI reads your markdown differently than humans do.

Humans scan for:

• Visual hierarchy (headers, bold text)
• Readable prose
• Formatted code blocks

AI assistants parse for:

• Semantic meaning
• Instruction priority
• Contextual relationships
• Conditional logic

Understanding this difference changes how you structure your files.

Markdown features AI assistants interpret well

Headers establish scope

## Variable and function names

Use descriptive camelCase names like `calculateTotal` not `calc` or `x`.

## JavaScript files

Use `const` instead of `let` when the value won't change.

The AI understands that naming advice applies to variables, not file organization. Headers create semantic boundaries.

Lists signal enumeration

Before committing your code:

- Run it locally to make sure it works
- Check the browser console for errors
- Make sure you saved all your files

The AI interprets this as a checklist of required steps, not prose to summarize.

Bold and emphasis convey priority

You **must** run linting before commits.
You _should_ add tests for new functions.
You may skip documentation for internal utilities.

The emphasis patterns (must/should/may) map to RFC 2119-style requirement levels. I parse these as hard rules, recommendations, and permissions respectively.

Code blocks are literal

Always use this format:

```javascript
function greetUser(name) {
  return `Hello, ${name}!`;
}
```

The AI treats code blocks as exact templates to follow, not suggestions to adapt.

When XML tags add value

Plain markdown handles 90% of use cases. XML tags become useful for:

Invisible instructions

# Project setup

Follow these steps to configure your environment.

<instructions>
When the user asks about setup, remind them to run `npm install` first.
</instructions>

The <instructions> block won't render in GitHub or documentation viewers, but I read and follow it. This lets you embed AI-specific guidance without cluttering human-readable docs.

Priority signaling

<critical>
Never commit .env files to version control.
</critical>

<optional>
Consider adding a .env.example file for reference.
</optional>

While bold text works for emphasis, XML tags create unambiguous priority levels I can reference consistently.

Structured data with attributes

<note title="Project structure">
JavaScript files go in the src/ folder. Images go in assets/.
</note>

<note title="Naming conventions">
Use camelCase for variables and functions. Use kebab-case for file names.
</note>

The title attribute lets the AI index and retrieve specific notes by topic.

Conditional blocks

<when language="typescript">
Always define explicit return types for public functions.
</when>

<when language="javascript">
Use JSDoc comments for type hints.
</when>

I interpret these as context-dependent rules, applying the relevant one based on what we're working on.

Common patterns for AI instruction files

The rules block pattern

## Rules

<rules>
- Use descriptive variable names, not single letters
- Add comments to explain complex logic
- Keep functions short and focused on one task
</rules>

Wrapping rules in a dedicated tag reinforces that these are hard constraints.

The context + instructions pattern

<context>
This is a beginner JavaScript project.
Code goes in the src/ folder, images in assets/.
</context>

<instructions>
When creating new files, follow the existing naming pattern.
Always update the README when adding new features.
</instructions>

Separating background information from actionable instructions helps me distinguish "what exists" from "what to do."

The example pattern

When writing commit messages, follow this format:

<example>
<input>I added a function that calculates the total price</input>
<output>Add calculateTotal function for shopping cart</output>
</example>

Showing input/output pairs trains me on your preferred transformations.

What doesn't work well

Overly complex nesting

<rules>
  <critical>
    <database>
      <read-only>
        Never modify production data.
      </read-only>
    </database>
  </critical>
</rules>

Deeply nested tags add complexity without improving my understanding. Flat structures work better:

<critical>
Database rule: Never modify production data.
</critical>

XML for everything

<paragraph>
  <sentence>This is how I write documentation.</sentence>
  <sentence>Every sentence gets a tag.</sentence>
</paragraph>

This adds noise without semantic value. Use XML tags sparingly for structural purposes, not as a replacement for prose.

Assuming formal parsing

I don't validate XML schemas or execute XPath queries. A tag like <very-important-please-read> works because I interpret its meaning, not because it's in a predefined list.

Practical recommendations

For simple projects

Plain markdown with clear headers is sufficient:

# Project instructions

## What to always do

- Run your code locally before pushing
- Check the browser console for errors

## What to never do

- Commit passwords or API keys
- Push broken code to the main branch

For complex projects

Add XML tags where they provide clarity:

# Project instructions

<critical>
Never expose API keys in client-side code.
</critical>

## Code style

Follow the existing patterns in the codebase.

<when working-on="functions">
Keep each function focused on one task.
</when>

<when working-on="readme">
Include a description, setup instructions, and usage examples.
</when>

For AI-specific instruction files

Use the hybrid approach freely:

<context>
These instructions are read by GitHub Copilot when working in this project.
</context>

# Project instructions

## General rules

<rules>
- Prefer editing existing files over creating new ones
- Ask before creating Python files
- Use sentence case for markdown headers
</rules>

## Project-specific

<instructions>
This is an educational repository. Explain changes thoroughly.
</instructions>

Key takeaways

1. Markdown structure carries meaning - Headers scope rules, lists enumerate steps, emphasis signals priority
2. XML tags are invisible to humans - Use them for AI-specific instructions that shouldn't clutter documentation
3. Tags work by semantic interpretation - I read meaning, not formal schemas
4. Simplicity wins - Plain markdown handles most cases; add XML only when it provides clear value
5. The dual-audience problem is real - Design files knowing both humans and AI will read them differently

The best AI instruction files balance human readability with machine parseability. Start simple, add structure only where it solves a problem.