I’ve created an AGENTS.md file in my repository to guide GitHub Copilot’s behavior. However, when I assign issues to the agent, it sometimes responds that no instructions are found and offers to create them.
Is this a bug or expected behavior? Does the agent require a specific format or location to detect AGENTS.md? Maybe this be related to recent changes in how Copilot agents interpret instruction files...
I’m trying to understand why the agent doesn’t always recognize the file, even when it’s present and correctly formatted.
I tried reading documentation but could not find anything to clearly answer my questions.
There are multiple kinds of instructions, the agents.md, but also the repo wide custom-instructions.md. One is specifically for the agent, the other to support copilot in general.
The offer to generate instructions targets the latter, custom-instructions.md.
There are basically multiple kinds of instructions you can add to your project:
.github/custom-instructions.md - This is the oldest feature that has been around since the beginning of this year. It is a central place where you can add instructions that apply to the whole repository. This file is used by both the Visual Studio Code as well as the Copilot Cloud Agent. It was generally used for coding conventions, review guidelines and describes the project structure..github/instructions/{your title}.instructions.md - Later this alternative was introduced. This structure allows you to break apart the ever growing custom-instructions.md into several smaller files with a more targeted name. You can also scope these instructions to specific file types and folders in your repository. This reduces the size of the context when for example editing a .cs file, by not including all the Typescript guidance.Agents.md - Is the most recent addition. It's a cross agent instructions file which is being standardized between AI coding agent vendors. It contains specific instructions for the agent. Things a human may know, your Visual Studio Extensions may automatically detect, but your agent may not know about. Things like how to build your project, where to pull dependencies from, whether there are limits on license types used, how to run your unit tests, common issues that may happen during debugging and test execution, how to kill your projects process in case it hangs, where it writes debug information to etc. Information that can help the agent perform better.The Visual Studio Code docs explain the usage of these files in more details. But as AI evolves, expect more changes to come and more new usage patterns to emerge. The whole world is still very much learning what is possible and what patterns work best when it comes to leveraging AI.
Visual Studio Code and the Copilot Cloud Agent have a built-in feature to generate instructions on your behalf. This feature tends to generate the copilot-instructions.md, not yet the other types. I suspect it won't be long before the feature is updated to generate all these kinds of files. So while the agent will use your agent.md file for guidance, it will still detect that the older instructions files are missing, and offer to build these for you as well. Or, maybe in the future, some of these files are removed again in favor of some new feature.
Ultimately they all serve similar purposes.