agents.md GitHub Copilot: Lessons from 2,500 Repositories

Introduction

The introduction of agents.md files in GitHub Copilot marks a turning point for development automation. This feature allows you to move beyond the concept of a generalist assistant to create a team of \"specialists\": a @docs-agent for documentation, a @test-agent for QA, or a @security-agent for vulnerability analysis.

However, configuring these agents is not trivial. An analysis of over 2,500 public agents.md files has highlighted why many fail and what characterizes those that bring real value to development teams.

Context: What is the agents.md file used for?

The agents.md file serves as an operating manual for your AI agent. This is where you define the "persona" (role), tech stack, project structure, and workflows. Through frontmatter and instructions, you transform Copilot from a generic suggester into an expert on your repository.

The Problem: Why many agents fail

The most common mistake is vagueness. Instructions like "You are a helpful assistant" do not work because they leave too much room for AI interpretation. Files that fail lack specific context, leading to incorrect code or unwanted changes.

\"My analysis of over 2,500 agents.md files revealed a clear divide between the ones that fail and the ones that work. The successful agents aren’t just vague helpers; they are specialists.\"

GitHub Blog Analysis

Solution: Golden rules for effective agents.md

To create a high-performing agent, you need to follow six key areas that emerged from the analysis of the best repositories:

1. Executable commands up front

Place relevant commands at the beginning of the file. Don't just list npm test, but include specific flags like pytest -v or npm run build. The agent will use these commands to validate its own output.

2. Concrete code examples

Show, don't tell. A code block illustrating your style (naming conventions, error handling) is much more effective than a long text description.

3. Strict Boundaries

Clearly define what the agent must not do. Use a three-tier structure:

• Always do: Write tests in tests/, run the linter.
• Ask first: Database schema changes, adding dependencies.
• Never do: Commit secrets or API keys, modify files in the vendor/ folder.

4. Stack Specificity

Be precise: "React 18 with TypeScript and Tailwind CSS" is better than "React Project". Specify versions and key libraries to reduce hallucinations.

Examples of Agents to implement

Here are three specialized agents recommended to start with:

• @docs-agent: Reads code in src/ and writes documentation in docs/. Key boundary: never modify source code.
• @test-agent: Writes and runs tests. Key boundary: can add tests, but must never remove an existing test just because it fails.
• @lint-agent: Fixes code style. Key boundary: purely stylistic changes, no alteration of logic.

Conclusion

Building effective agents requires iteration. Start with a simple task, define a clear persona, and set strict boundaries in your agents.md file. For more details, check the original article and templates on the GitHub blog.

FAQ

Here are answers to frequently asked questions about configuring agents.md and using agents in GitHub Copilot.

What exactly is an agents.md file?

It is a Markdown configuration file that defines the persona, skills, executable commands, and operational boundaries of a custom AI agent within GitHub Copilot, transforming it into a specialist for your project.

How can I prevent the AI agent from damaging code?

You must set explicit \"boundaries\" in the agents.md file. Use clear sections like \"Never do\" to prohibit specific actions, such as committing secret keys, modifying critical config files, or deleting failing tests.

What is the most common mistake when creating these agents?

The main mistake is being too vague. A generic prompt like \"You are a coding assistant\" is ineffective. Agents work best when they have a hyper-specialized role (e.g., \"You are a technical writer expert in Markdown\") and detailed instructions.

Which agents should I create first?

It is recommended to start with low-risk, high-impact agents: a @docs-agent for automatic documentation generation, a @test-agent for writing unit tests, and a @lint-agent for automatically fixing code style.