To give GitHub Copilot durable project context, put shared guidance in .github/copilot-instructions.md, add folder-specific rules in .github/instructions/, and use AGENTS.md for agent instructions where the Copilot feature you use supports them. These files can explain what the codebase does and how to build, test, and review changes—but they are guidance, not a guarantee that Copilot will follow every rule.
Which instruction file should you use?
GitHub documents three instruction mechanisms with different scopes. Choose based on where a rule should apply, then verify that the Copilot surface and environment you use support that file type.
As an Amazon Associate I earn from qualifying purchases.
| Mechanism | Scope and location | Best fit |
|---|---|---|
| Repository-wide custom instructions | .github/copilot-instructions.md |
Conventions and workflow guidance that should apply broadly across the repository. |
| Path-specific custom instructions | One or more *.instructions.md files in .github/instructions/, with an applyTo pattern |
Rules for matching folders or files, such as a distinct test, frontend, or API area. |
| Agent instructions | AGENTS.md |
Instructions intended for AI agents. GitHub documents nearest-file precedence in its repository-instructions guidance. |
GitHub’s repository-instructions guide describes these file types and setup: Adding repository custom instructions for GitHub Copilot.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →How to add project context
- Write shared guidance. Add
.github/copilot-instructions.mdat the repository root. Keep it focused on facts and practices relevant to most work in the project. - Separate rules by path when needed. Create a
*.instructions.mdfile under.github/instructions/and use itsapplyTopattern to specify matching paths. For example, a rule meant only for tests should not be presented as a repository-wide requirement. - Add agent-specific guidance where supported. Use
AGENTS.mdfor instructions intended for agents, and follow GitHub’s documented nearest-file precedence for nested files. - Check support for your exact workflow. Consult GitHub’s custom-instructions support matrix for the feature and environment you use; file support is not uniform across Copilot surfaces.
- Validate the result. Review generated changes, then run the project’s normal checks. Instructions can help provide context but do not replace tests or code review.
For GitHub’s documented IDE workflow, repository-wide instructions and applicable path-specific instructions can both be used. See Adding repository custom instructions for GitHub Copilot in your IDE for that workflow’s details.
#1 Best Overall
What belongs in useful project instructions?
GitHub’s project-improvement tutorial recommends giving Copilot an accurate picture of the codebase and how the team works with it. Useful context includes:
- Project summary: what the software does and the important boundaries of the codebase.
- Structure: where key components live and how they relate.
- Build and validation: the commands or practices for building, formatting, linting, and testing.
- Contribution requirements: relevant review or merge requirements.
- Technical principles: architectural choices and other durable constraints contributors should respect.
Before adding rules, check existing instructions and correct anything stale. GitHub presents these as recommended project details, not evidence of a guaranteed improvement in output. See Using GitHub Copilot cloud agent to improve a project.
Will the same files work in every Copilot tool?
No. GitHub distinguishes support across GitHub.com Copilot Chat, cloud agent, code review, IDEs, and other environments. The available instruction types and behavior depend on the surface; do not assume that a file recognized in one workflow is available in another. Check the official support matrix before relying on a particular setup.
Free tools Windows power users keep installed
One-click scans. No signup required.
When a path-specific file matches the work, GitHub documents it being used alongside repository-wide instructions in the relevant IDE workflow. That should not be generalized to every Copilot feature or environment.
How reliable are custom instructions?
Instructions add context to relevant requests, but they do not make Copilot deterministic. GitHub Docs cautions: “Due to the non-deterministic nature of AI, Copilot may not always follow your custom instructions in exactly the same way every time they are used.” Treat instructions as guidance: keep them clear and relevant, and verify code with the checks your project requires. GitHub explains this limitation in About customizing GitHub Copilot responses.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When do instructions need more than files?
Instruction files are for explaining project expectations. GitHub’s broader customization documentation also covers specialized agents and MCP servers. In supported cloud-agent and code-review use cases, MCP servers can provide access to external tools and data; this is a separate kind of integration, not a substitute for repository guidance. Availability and setup depend on the feature, so consult GitHub’s Customize Copilot documentation for current options.
Quick Recap
Best Value
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
