How to write a great agents.md

The Core Concept: A Team of Specialists#

Instead of relying on one general "helpful assistant," the article recommends creating multiple, highly specialized agents. Each agent has a distinct persona, specific commands it can run, and strict boundaries.

1. How to Create Multiple Agents#

You define each agent in a separate Markdown file located in your repository at .github/agents/.

Recommended Agent "Roster"#

To improve your workflow, the article suggests building these specific agents:

• @docs-agent (.github/agents/docs-agent.md)
  • Role: Expert technical writer.
  • Job: Reads code in src/ and updates documentation in docs/.
  • Workflow Improvement: Automates documentation updates without cluttering your creative coding time.
• @test-agent (.github/agents/test-agent.md)
  • Role: QA Engineer.
  • Job: Writes unit/integration tests and runs them.
  • Boundary: "Never remove a failing test unless authorized."
• @lint-agent (.github/agents/lint-agent.md)
  • Role: Code Janitor.
  • Job: Fixes formatting and style issues.
  • Workflow Improvement: Low-risk automation that keeps code clean.
• @security-agent (.github/agents/security-agent.md)
  • Role: Security Analyst.
  • Job: Analyzes code for vulnerabilities and secrets.

---

2. How to Structure an Agent for Success#

Most agents fail because they are too vague (e.g., "You are a helpful coding assistant"). To improve your workflow, every agents.md file must cover these six core areas:

A. The Header (Frontmatter)#

Define the handle you will use to call the agent in Copilot.

yamlCopy
---
name: docs-agent
description: Expert technical writer for this project
---

B. The Persona#

Be hyper-specific about who they are.

Bad: "You help with docs." Good: "You are an expert technical writer. You are fluent in Markdown and TypeScript. You write for a developer audience focusing on clarity."

C. Project Knowledge (Context)#

List the tech stack and file structure so the agent doesn't guess.

Tech Stack: React 18, TypeScript, Vite File Structure: src/ is for code, docs/ is for documentation.

D. Executable Commands (The "Hands")#

This is the biggest workflow improver. Give the agent the exact commands to validate its own work.

• Build: npm run docs:build (Checks for broken links)
• Lint: npx markdownlint docs/ (Validates syntax)

E. Code Style Examples#

Don't explain your style; show it.

"Follow this pattern for all functions:" [Insert a real code snippet from your project here]

F. Boundaries (The Safety Rails)#

Prevent the agent from breaking things. Use a "Traffic Light" system:

• ✅ Always do: Write to docs/, run markdownlint.
• ⚠️ Ask first: Before modifying existing major documents.
• 🚫 Never do: Modify code in src/, commit secrets.

---

3. Starter Template#

You can copy this template into .github/agents/your-agent-name.md to get started immediately.

markdownCopy
---
name: [agent-name]
description: [Short description]
---
You are an expert [Role] for this project.

## Persona
- You specialize in [Task]
- Your output must be [Specific Quality, e.g., "production-ready code"]

## Project Knowledge
- **Tech Stack:** [React / Python / etc.]
- **File Structure:**
  - `src/` – Source code
  - `tests/` – Test files

## Tools You Can Use
- **Test:** `npm test` (Must pass before answering)
- **Lint:** `npm run lint --fix`

## Boundaries
- ✅ **Always:** Write to `src/`, run tests
- 🚫 **Never:** Commit secrets, edit `node_modules/`

Summary of Workflow Improvements#

1. Less Context Switching: You don't have to explain your file structure or coding style every time you ask a question; it's hardcoded into the agent.
2. Self-Correction: Because you gave the agent "Commands" (like npm test), it can write code, run the test, fail, fix the code, and run the test again—all before showing you the answer.
3. Safety: Explicit boundaries prevent AI from hallucinating changes to critical config files or secrets.