Instruction Files
Instruction files are text files that inject persistent context into your AI coding assistant — they tell it about your project, coding standards, and preferences without you repeating yourself every session.
30-second version: Every time you start a Copilot session, you can make it read a file that describes your project. This means Copilot knows your tech stack, naming conventions, and preferences before you say a word. These files don’t give Copilot new abilities — they give it better context.
⚠️ Instruction files are NOT agents. Despite names like AGENTS.md, these files are plain text — they’re read as prompt context, not executed. Calling a file AGENTS.md does not create an agent. It tells agents what to do. The agent is still the agent. The file is just instructions.
The main instruction files
| File | Who reads it | What it’s for |
|---|---|---|
.github/copilot-instructions.md | GitHub Copilot (IDE + coding agent) | Project-wide Copilot behaviour: stack, style, preferences |
AGENTS.md | Copilot coding agent + other agentic tools | Agent-specific rules: how to run tests, what to avoid, PR conventions |
.cursorrules | Cursor | Project-specific Cursor behaviour |
CLAUDE.md | Anthropic’s Claude coding agent | Instructions for Claude when it works on your codebase |
AGENTS.md is a community-driven convention, not a GitHub-owned specification. Different tools interpret it differently. Always check the documentation for your specific tool.
What to put in instruction files
- Your tech stack and language versions
- Coding style preferences (e.g., “use TypeScript strict mode”, “prefer functional patterns”)
- Testing conventions (e.g., “always write unit tests for new functions”)
- What NOT to do (e.g., “don’t use deprecated APIs”, “don’t commit secrets”)
- Project structure overview (e.g., “API routes are in
/src/routes/”) - PR and commit message conventions
copilot-instructions.md vs AGENTS.md
copilot-instructions.md is read by Copilot in every context — inline suggestions, chat, agent mode. AGENTS.md is read specifically by agentic workflows and the Copilot coding agent. If you only write one, start with copilot-instructions.md. You can always add AGENTS.md later when your agentic workflows become more complex and need their own rules.
Dive deeper
- Copilot Coding Agent — the agent that reads AGENTS.md
- What is an Agent? — agents vs instruction files
Related Concepts
- What is an Agent? — Agents are what instruction files configure
- Copilot Agent Mode — Where copilot-instructions.md takes effect in your IDE
📍 Layer 4a — Instructions · Back to the AICA Onion
What’s next?
- Writing Effective Copilot Instructions — practical patterns for
copilot-instructions.mdfiles that actually get read - Landscape Overview — how all the tools and players fit together
- Glossary — quick-reference definitions for every term on this site