If you’ve used an AI coding assistant recently, you’ve probably noticed something: they all want a Markdown file.

GitHub Copilot reads .github/copilot-instructions.md. Cursor reads .cursor/rules/. Claude Code reads CLAUDE.md. Windsurf reads .windsurf/rules. Google’s Jules reads JULES.md. And the universal standard? AGENTS.md --- now used by over 60,000 open-source repositories and stewarded by the Linux Foundation’s Agentic AI Foundation.

Markdown has gone from a documentation format to the operating system for AI coding agents.

What Is AGENTS.md?

AGENTS.md is a simple, open-format Markdown file that lives in your repository and acts as a briefing packet for AI coding agents. Think of it as README.md’s counterpart:

README.md is for humans: quick starts, project descriptions, badges
AGENTS.md is for AI agents: build steps, test commands, coding conventions, architectural decisions

The agent reads the nearest file in the directory tree, so the closest one takes precedence. Every subproject can ship tailored instructions.

What Is CLAUDE.md?

CLAUDE.md is specifically for Anthropic’s Claude Code. It’s read automatically at the start of each session and holds project-specific instructions you’d otherwise repeat in every prompt.

A good CLAUDE.md typically includes:

Project context: A one-liner that orients Claude about what the project does
Code style: Your formatting preferences, naming conventions, patterns to follow
Commands: How to run tests, build, lint, and deploy
Architecture notes: Key decisions Claude should respect

The recommended approach: put shared instructions in AGENTS.md (so all AI tools benefit), then add Claude-specific features to CLAUDE.md.

The Full Landscape of AI Instruction Files

Here’s every major AI coding tool and its Markdown convention:

Tool	File	Format
GitHub Copilot	`.github/copilot-instructions.md`	Markdown
Cursor	`.cursor/rules/*.md`	Markdown
Claude Code	`CLAUDE.md`	Markdown
Windsurf	`.windsurf/rules`	Markdown
Google Jules	`JULES.md`	Markdown
Universal	`AGENTS.md`	Markdown

Notice the pattern? It’s all Markdown. Every single one.

Why Markdown Won

Markdown is the perfect format for AI instruction files because:

LLMs understand it natively --- it’s the most common format in their training data
It’s human-readable --- developers can review and edit instructions easily
It’s version-controllable --- lives in git alongside your code
It’s lightweight --- no parsing overhead, no special tooling needed
It’s universal --- works across every AI tool, editor, and platform

As Visual Studio Magazine put it: in agentic AI, it’s all about the Markdown.

Best Practices for Writing Agent Instructions

Based on analysis of thousands of repositories:

Start minimal. Add rules only when you notice the agent repeatedly making the same mistake. Over-specified instructions can confuse more than help.

Be specific about commands. Don’t say “run the tests” --- say pnpm test or pytest -x tests/.

Document your architecture. If your project uses a specific pattern (like message passing between a content script and service worker), explain it. The agent can’t infer architectural decisions from code alone.

Include what NOT to do. Negative instructions are surprisingly effective: “Never modify the database schema directly” or “Don’t use class components, always use hooks.”

How Save Fits Into This World

If you’re building agent instruction files, you’re probably also saving reference material from the web: documentation pages, Stack Overflow answers, GitHub READMEs, API references.

Save converts any of these web sources to clean Markdown with one click --- perfect for building the context your AI agents need. Save a documentation page, paste the Markdown into your AGENTS.md or reference docs, and your AI coding assistant instantly has the context it needs.

The workflow:

Find useful documentation or code examples on the web
Click Save to convert to Markdown
Reference or include in your agent instruction files
Your AI coding assistant works better with every save

The Future: Markdown as AI’s Control Surface

Microsoft and GitHub are now treating Markdown as a stable, auditable control surface for AI behavior. It’s not just documentation anymore --- it’s the interface between human intent and AI execution.

We’re seeing Markdown files serve three distinct roles:

Documentation: Explains a system to humans
Instruction: Constrains and steers AI behavior
Skill: Bundles instructions with resources so agents can repeat workflows

This trend is only accelerating. As AI coding assistants become more capable, the Markdown files that guide them become more important.

Save converts any webpage to clean Markdown with one click. Perfect for building reference libraries, capturing documentation, and creating context for your AI coding workflows. Try Save free.