Mastering agents.md: Transforming GitHub Copilot with Role-Based Agents

What if GitHub Copilot could be more than a generic assistant? With the new agents.md feature, you can define agents with specialized roles and detailed instructions, unlocking more targeted automation for your projects. The effectiveness of Copilot now depends on how well you articulate each agent’s purpose and boundaries.

This upgrade replaces the chat modes that allowed you to customize the behavior of CoPilot through a similar markdown file. You can now migrate your chat modes to agents and utilize specialized sub agents to address your workflow requirements.

To use agents in github copilot put your agents.md file in .github/agents/YOUR-agent.md

Key Ingredients of High-Impact agents.md Files

The main reason agents.md files fall short is vagueness. Generic prompts like “You are a helpful coding assistant” don’t cut it. The best files are precise, actionable, and tailored to unique project needs. Here’s what sets them apart:

• Lead with commands: Start with actionable commands, including exact flags and options (e.g., npm test --coverage Copy Copy Copy).
  
  
• Show, don’t tell: Use real code snippets to demonstrate style and expectations, instead of lengthy explanations.
  
  
• Set explicit boundaries: Clearly list what agents must never do, such as modifying secrets or production configs, to prevent mistakes.
  
  
• Specify your stack: Name frameworks, exact versions, and critical dependencies so agents act within the right environment.
  
  
• Address six core areas: Effective files cover commands, testing, project structure, code style, git workflow, and boundaries.

Defining the Agent Persona and Scope

Successful agents are sharply defined. For example, an agent for documentation might be described as “an expert technical writer fluent in Markdown and TypeScript, responsible for generating docs from src/ Copy Copy Copy to docs/ Copy Copy Copy.” The agents.md should clarify:

• What files or directories the agent reads and writes
• Which commands it can execute
• Documentation standards and code style
• What it must always, sometimes, or never do

Boundaries work best when grouped into “always do,” “ask first,” and “never do” with examples for clarity.

Start Simple - Iterate Fast

Don’t try to build a Swiss Army knife agent. Begin with a single, focused task like adding unit tests or writing documentation. An initial agents.md only needs a name, description, and persona. Use Copilot itself to draft the first version, then refine it by adding commands, boundaries, and project-specific details.

Six Specialist Agents to Supercharge Your Workflow

Examples of agents you can build to give your agent the tools it needs to be an end to end solution for your development workflow.

• @docs-agent: Generates and validates docs, writes only to docs/ Copy Copy Copy, never changes source code.
  
  
• @test-agent: Writes and runs tests in tests/ Copy Copy Copy, never removes failing tests without approval.
  
  
• @lint-agent: Fixes code style and formatting, never alters logic.
  
  
• @api-agent: Builds API endpoints, alters routes, but asks before changing schemas.
  
  
• @dev-deploy-agent: Handles local builds and deployments, only to dev environments, requests approval for risky actions.

Each agent should have commands, boundaries, and examples tailored to your stack and directory structure.

Use a Proven Template

A solid template should always cover: agent persona, project knowledge, tools and commands, code standards, and boundaries. Include concrete code samples that show both good and bad examples to clarify expectations and common pitfalls.

---
name: your-agent-name
description: [One-sentence description of what this agent does]
---

You are an expert [technical writer/test engineer/security analyst] for this project.

## Persona
- You specialize in [writing documentation/creating tests/analyzing logs/building APIs]
- You understand [the codebase/test patterns/security risks] and translate that into [clear docs/comprehensive tests/actionable insights]
- Your output: [API documentation/unit tests/security reports] that [developers can understand/catch bugs early/prevent incidents]

## Project knowledge
- **Tech Stack:** [your technologies with versions]
- **File Structure:**
  - `src/` – [what's here]
  - `tests/` – [what's here]

## Tools you can use
- **Build:** `npm run build` (compiles TypeScript, outputs to dist/)
- **Test:** `npm test` (runs Jest, must pass before commits)
- **Lint:** `npm run lint --fix` (auto-fixes ESLint errors)

## Standards

Follow these rules for all code you write:

**Naming conventions:**
- Functions: camelCase (`getUserData`, `calculateTotal`)
- Classes: PascalCase (`UserService`, `DataController`)
- Constants: UPPER_SNAKE_CASE (`API_KEY`, `MAX_RETRIES`)

**Code style example:**
```typescript
// ✅ Good - descriptive names, proper error handling
async function fetchUserById(id: string): Promise<User> {
  if (!id) throw new Error('User ID required');
  
  const response = await api.get(`/users/${id}`);
  return response.data;
}

// ❌ Bad - vague names, no error handling
async function get(x) {
  return await api.get('/users/' + x).data;
}
Boundaries
- ✅ **Always:** Write to `src/` and `tests/`, run tests before commits, follow naming conventions
- ⚠️ **Ask first:** Database schema changes, adding dependencies, modifying CI/CD config
- 🚫 **Never:** Commit secrets or API keys, edit `node_modules/` or `vendor/`
 Copy Copy

Agents Can Do More Than Code

Personally I have been using chat modes and now agents for a variety of tasks from content creation to scientific paper decomposition and full stack software development. My agents are organized around a tasks such as creating a research paper blog then are decomposed into sub agents that handle research, article outlining, content generation, review and finally publication. 

This format works well for me since I am already a power VS Code user. I am able to quickly generate new content but more importantly I have access to the instructions, prompts and agents than I can modify quickly to iterate on new models and requirements. While this approach won't work for everyone, it has proven to be a cost and time efficient process for me.

Final Thoughts: Iterate for Maximum Value

The strongest agents.md files are specific, actionable, and role-driven. They empower Copilot with clear personas, commands, boundaries, and examples. Start small, refine as you go, and leverage your agents.md as a living document. Over time, you’ll unlock safer, smarter, and more productive automation in your development workflow.

Source: How to write a great agents.md: Lessons from over 2,500 repositories – The GitHub Blog