December 22, 2025
💡 Templates & Examples: Looking for complete instruction file examples? Check out the gh-copilot-templates repository:
- Generalized templates to copy and customize
- Personalized examples with AGENTS.md, copilot-instructions.md, and path-specific files
The more precise your prompt, the better the output. That's not some hot take, it's just how language models work. But typing a novel about your conventions every time you ask an agent to do something is soul-crushing.
That's what instruction files are for. They let you write your rules once, then have the agent read them automatically based on context. No copy-pasting. No forgetting which constraints apply where.
There are three types of instruction files. The first two—AGENTS.md and copilot-instructions.md—both apply repo-wide. They exist because multiple companies are trying to establish new standards. They overlap intentionally. Different tools prioritize different formats, but understanding which fits your workflow makes choosing less confusing. Most people will pick one, not both.
AGENTS.md (Agents File)A cross-platform standard supported by 60k+ open-source projects. AGENTS.md is stewarded by the Agentic AI Foundation (AAIF), established under the Linux Foundation as a neutral home for agent standards.
AGENTS.md works across dozens of tools: GitHub Copilot, Cursor, Codex, Zed, Windsurf, Gemini CLI, and more.
You can have multiple AGENTS.md files nested in your repo (one per subproject). The closest one to the file you're editing takes precedence. This is useful in monorepos where different services have different conventions.
For it to work in VS Code, you need to enable chat.useAgentsMdFile in settings. It's currently treated similarly to copilot-instructions.md—always applied (when enabled).
What I use AGENTS.md for:
?. over !)Use AGENTS.md if: You want flexibility to switch between Cursor, Gemini CLI, Windsurf, or other AI coding tools without rewriting your instructions. While Anthropic is part of the Agentic AI Foundation, they haven't adopted AGENTS.md for Claude Code. Instead, they're pushing their own standards: CLAUDE.md for general guidance and Agent Skills for reusable, composable capabilities. If you're using Claude Code, you'd need CLAUDE.md instead. Portable across non-Anthropic tools. Future depends on Anthropic's adoption.
.github/copilot-instructions.md (Copilot File)GitHub's repo-wide baseline for the GitHub/VS Code ecosystem. One file. Always applied to every prompt, automatically.
To enable in VS Code:
github.copilot.chat.codeGeneration.useInstructionFiles to true in your settings.github/copilot-instructions.md file at the root of your workspaceIf you're using copilot-instructions.md and not using AGENTS.md in the root of your directory, this is where you'd put your general conventions—code quality standards, tech stack, development workflow, testing patterns. It is the general repo-wide baseline for GitHub Copilot users.
Don't duplicate these instructions in both files. That wastes tokens better spent on codebase context. Pick one file.
However, if you're using both AGENTS.md and copilot-instructions.md simultaneously (an advanced pattern), specialize the Copilot file to contain only VS Code-specific Copilot features. Specifically: VS Code's built-in Copilot Chat tools (like #tool:githubRepo, #tool:edit/editFiles, etc.) that are unique to GitHub Copilot and won't exist in other tools. Keep general conventions and MCP-based tools in AGENTS.md instead—those are generalizable across all agents using the Model Context Protocol.
What can optionally go here if using both files:
#tool:search/codebase to search the codebase instead of guessing" (see full list of tools)Use copilot-instructions.md if: You're committed to the GitHub/VS Code/Copilot ecosystem and don't plan to switch to other AI coding tools. Lower friction. Less moving parts. Works everywhere Copilot is supported.
The instruction file ecosystem is still settling—different companies are betting on different standards. What matters is that you pick one and stick with it. The exact format will matter less over time as tools mature and converge on common patterns.
.github/instructions/*.instructions.md (Instructions Files)These are specialized instruction files. Unlike the first two, they aren't auto-applied to every prompt. Instead, the applyTo frontmatter property defines a glob pattern of files they apply to.
For example, here's a complete tests.instructions.md file:
---
applyTo: "__tests__/**/*.ts,__tests__/**/*.tsx"
---
# Testing Conventions
When writing tests for this repository:
- Use descriptive test names that clearly state what behavior is being tested: `it("should validate email with a valid address")`
- Keep each test focused on a single behavior—don't test multiple things in one test
- Always test both success and error cases
- Use meaningful assertion messages to explain what failed: `expect(result).toBe(true, "Email validation should accept valid addresses")`
- For async operations, use `async/await` rather than callbacks
- Mock external dependencies (API calls, file system, etc.)
- Keep test files colocated with source files when possible, or mirror the directory structure in `__tests__`This file will be automatically injected whenever you're working on test files. The agent will read these conventions and apply them without you having to repeat the instructions in every prompt.
You can also create multiple .instructions.md files. For example:
dal.instructions.md with applyTo: "lib/dal/**/*.ts" for Data Access Layer patternsdocs.instructions.md with applyTo: "docs/**/*.md" for documentation standardsVS Code automatically serves the matching files based on which files the agent is touching. You can also manually attach them via the Chat UI.
What I use them for:
The power here is precision. Each file only activates when relevant. No context bloat. No manual reference needed. The agent immediately sees the rules that matter for the current task.
These files can be saved to your user profile and reused across projects (unlike the copilot file, which is workspace-specific).
Custom instruction files are complementary. Start with one, then add more as your needs grow.
Level 1 (Baseline): Create .github/copilot-instructions.md with your top 3–5 conventions. This is all most teams need. One file. No complexity.
Level 2 (Optional): Add AGENTS.md if you want portability across multiple AI coding tools, or if you need nested instruction specialization. This allows you to define different rules for different folders—like keeping React conventions in frontend/AGENTS.md and API standards in backend/AGENTS.md.
Level 3 (Advanced): Add .github/instructions/*.instructions.md files for specific file types or folders. This is when you notice patterns: "We keep fixing logging in every prompt," or "Tests always need reminding about structure." Each specialized file is optional, scoped to what matters for that part of your codebase.
Don't create all the files at once. You'll end up with bloat and forget what they're for. Add them as friction points emerge.
Instruction files are processed on every request. Wasteful formatting burns tokens:
**bold**and_italic_ — LLMs ignore visual formatting- not - [ ] — checkboxes are for humansLong instruction files make models less likely to follow all instructions. If you're using an LLM to draft your instruction files, watch for this. Models love to add formatting for readability, but that only wastes your token budget.
Ambiguity is the enemy. An agent's quality degrades linearly with the fuzziness of your instructions. "Use TypeScript" is vague. "TypeScript strict mode, no implicit any, exhaustive switch checks, and prefer ?. over ! assertions" is actionable.
Writing these instructions down forces you to clarify your own preferences. You'll find inconsistencies in your codebase ("Wait, why do we use both forms?"), and fixing them is worth the time.
Plus, it scales. New engineers (or new agents) don't have to reverse-engineer your conventions from reading code. They read a file.
You'll see some settings marked as "Experimental" (like chat.useNestedAgentsMdFiles). These exist because VS Code is still figuring out the right interaction patterns. Nested AGENTS.md files are powerful but introduce complexity: which file takes precedence if you have conflicting instructions? How should the agent decide? These aren't fully settled yet, so they're behind experimental flags while the team gathers feedback.
Don't let that scare you. Experimental doesn't mean broken—it means the API might change. But it works today.
While instruction files are a massive upgrade, they aren't magic. These models are stochastic—they roll dice. Sometimes they will look you in the eye (metaphorically) and completely ignore your AGENTS.md for no reason.
Even the most performant models (like Claude Opus 4.5) suffer from this in my experience. It's disappointing but true. All of the new models available at the time of writing cannot be completely relied on to follow all your instructions all the time, no matter how detailed they get.
That's why you still need deterministic guardrails. Use ESLint, Prettier, and CI checks to enforce the hard rules. Let the instruction files handle the "vibe" and the complex patterns, but let the linter handle the law.
In the next log, we'll talk about .agent.md files (don't confuse these with AGENTS.md—naming collision that nobody's happy about). These are custom agents: specialized versions of Copilot itself, configured for specific workflows.
For more detailed official documentation on custom instructions:
Model Note: This article was written with the help of Claude Haiku 4.5. No other models involved.