When you write a README, you think about human readers. When you write a .github/copilot-instructions.md, you’re writing for an AI. But here’s what most people miss: AI reads your markdown differently than humans do.

Humans scan for visual hierarchy, readable prose, and formatted code blocks.

AI parses for semantic meaning, instruction priority, contextual relationships, and conditional logic.

Understanding this difference changes how you structure your files.

What AI interprets 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. AI parses these as hard rules, recommendations, and permissions.

Code blocks are literal

AI treats code blocks as exact templates to follow, not suggestions to adapt. If you show a pattern in a code block, expect the AI to replicate it precisely.

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 AI reads and follows it. This lets you embed AI-specific guidance without cluttering human-readable docs.

The dual-audience problem is real

The best AI instruction files balance human readability with machine parseability.

I recommend starting simple. Use clear headers, organized lists, and strategic bold text. Add XML tags only when you need invisible instructions or unambiguous priority levels.

The same file needs to make sense to a colleague reading your repo AND to the AI assistant working in it. Structure matters more than you think.

The developers building AI coding assistants chose markdown for a reason: it’s what developers already use. Your skill in writing clear, structured markdown now extends to communicating effectively with AI.