Markdown Files for AI Coding Agents
AI coding tools increasingly use Markdown files to understand projects, follow repository instructions and load reusable capabilities. This guide compares the most common files and explains what each one is for.
Quick comparison
| File | Purpose | Typical scope |
|---|---|---|
| AGENTS.md | Instructions for coding agents working in a repository | Repository or directory |
| CLAUDE.md | Persistent instructions and project context for Claude Code | User, project or directory |
| GEMINI.md | Context and instructions for Gemini CLI | Global, workspace or directory |
| copilot-instructions.md | Repository-wide custom instructions for GitHub Copilot | Repository |
| SKILL.md | Instructions and metadata for a reusable Agent Skill | Skill |
| PROJECT-GOALS.md | Documents project objectives, requirements and boundaries | Project |
The files explained
AGENTS.md
Repository instructions intended for coding agents. Useful for build commands, tests, conventions and development workflows.
Read the AGENTS.md guide →CLAUDE.md
Persistent project instructions and context used by Claude Code.
Read the CLAUDE.md guide →GEMINI.md
Context instructions used by Gemini CLI to provide project-specific guidance.
Read the GEMINI.md guide →copilot-instructions.md
Repository-wide custom instructions for GitHub Copilot.
Read the Copilot guide →PROJECT-GOALS.md
A simple project document dedicated to objectives, requirements, scope and non-goals.
Generate PROJECT-GOALS.md →Which file should you use?
The right file depends on what you want to communicate.
| If you want to... | Consider |
|---|---|
| Give general repository instructions to coding agents | AGENTS.md |
| Give project instructions specifically to Claude Code | CLAUDE.md |
| Give project context to Gemini CLI | GEMINI.md |
| Configure repository instructions for GitHub Copilot | .github/copilot-instructions.md |
| Package a reusable agent capability | SKILL.md |
| Document project objectives and boundaries | PROJECT-GOALS.md |
Can you use several files together?
Yes. These files can serve different purposes. A repository may contain tool-specific instructions, general agent instructions and separate project documentation.
For example:
my-project/ │ ├── README.md ├── PROJECT-GOALS.md ├── AGENTS.md ├── CLAUDE.md ├── GEMINI.md │ ├── .github/ │ └── copilot-instructions.md │ ├── skills/ │ └── code-review/ │ └── SKILL.md │ └── src/
Instructions vs goals
One useful way to avoid mixing everything into a single instruction file is to separate the project's destination from agent-specific working instructions.
What are we building? What should it achieve? What are the requirements? What is outside the scope?
Agent instructions answer:How should the coding agent work inside this repository?
A simple starting structure
If you are starting an AI-assisted software project, a minimal structure could be:
my-project/ │ ├── README.md ├── PROJECT-GOALS.md ├── AGENTS.md └── src/
Then add tool-specific files when they are useful for your workflow.
Start with the project goals
Define the objectives, requirements and boundaries of your project in a structured Markdown file.
Generate PROJECT-GOALS.md