Skip to content

Commit a2da511

Browse files
csharpfritzcsharpfritz
authored
Merge pull request #30 from csharpfritz/content/2026-03-04-custom-copilot-agent
📅 [2026-03-04] Article: Create Your First Custom Copilot Agent (.agent.md)
2 parents 53b0834 + bc107a0 commit a2da511

1 file changed

Lines changed: 310 additions & 0 deletions

File tree

‎Content/Tips/create-your-first-custom-copilot-agent.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
---
2+
title: "Create Your First Custom Copilot Agent: Authoring .agent.md Files for Specialized AI Assistants"
3+
description: "Learn how to create custom Copilot agents using .agent.md files. Build specialized AI assistants with defined roles, boundaries, and tools for your team."
4+
category: "GitHub Copilot"
5+
tags: ["github-copilot", "agents", "agent-md", "customization", "getting-started"]
6+
difficulty: "Beginner"
7+
author: "Copilot That Jawn"
8+
publishedDate: "2026-03-04"
9+
lastModified: "2026-03-04"
10+
series: "Copilot Customization"
11+
part: 1
12+
featured: true
13+
---
14+
15+
# Create Your First Custom Copilot Agent: Authoring .agent.md Files for Specialized AI Assistants
16+
17+
Custom Copilot agents let you create specialized AI assistants that appear in the `@` menu within [Copilot Chat](https://docs.github.com/en/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). Instead of one general-purpose assistant, you can build agents with specific roles—like a "code reviewer," "documentation writer," or "database expert"—each with its own expertise, boundaries, and tools.
18+
19+
If you've already explored [`copilot-instructions.md`](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) (global rules for your whole project) or [`SKILL.md`](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot#creating-a-skill-file) files (reusable playbooks), agents are the next step: they're **named personas that Copilot activates when you call them by name**.
20+
21+
## What's a Custom Copilot Agent?
22+
23+
An agent is a personality layer on top of Copilot. When you invoke it by name, Copilot takes on that role, follows the agent's instructions, respects its boundaries, and uses only the tools you've defined for it.
24+
25+
Think of it like this:
26+
27+
- **`copilot-instructions.md`**: Global rules everyone follows (e.g., "all TypeScript must be strict mode").
28+
- **`SKILL.md`**: Reusable workflows (e.g., "here's how to run our PR checklist").
29+
- **`.agent.md`**: A named specialist persona (e.g., "I'm your security auditor—I review code for vulnerabilities").
30+
31+
Agents are powerful because:
32+
- ✨ **Named and discoverable** — teammates see them in the @ menu
33+
- 🎯 **Focused expertise** — each agent has a clear role and boundaries
34+
- 🔧 **Tool-aware** — you control what commands and tools each agent can use
35+
- 📦 **Teamable** — share them across your repo so everyone gets the same specialist
36+
37+
## Where agents live
38+
39+
Store `.agent.md` files in your repository:
40+
41+
```
42+
your-repo/
43+
└── .github/
44+
└── agents/
45+
├── code-reviewer.agent.md
46+
├── docs-writer.agent.md
47+
└── security-auditor.agent.md
48+
```
49+
50+
Copilot scans `.github/agents/` and makes each agent available by name in chat.
51+
52+
You can also store personal agents in `~/.copilot/agents/` (on your machine only) or share them organization-wide in `.github-private/agents/`.
53+
54+
## The .agent.md file format
55+
56+
Every agent file needs two parts:
57+
58+
1. **YAML frontmatter** (at the top, between `---` markers) — metadata like name, description, and allowed tools
59+
2. **Markdown body** — your agent's persona, rules, examples, and instructions
60+
61+
Here's the structure:
62+
63+
```markdown
64+
---
65+
name: agent-name
66+
description: "What this agent does."
67+
target: github-copilot
68+
tools:
69+
- npm
70+
- git
71+
disable-model-invocation: false
72+
---
73+
74+
# Persona
75+
You are a [role]. Your job is to [responsibility].
76+
77+
# Boundaries
78+
Never touch [dangerous places]. Only modify [safe areas].
79+
80+
# Commands
81+
- npm test
82+
- npm run lint
83+
84+
# Code style preferences
85+
...and so on
86+
```
87+
88+
### Frontmatter fields explained
89+
90+
| Field | Required? | Example | Notes |
91+
|-------|-----------|---------|-------|
92+
| `name` | ✅ Yes | `code-reviewer` | Lowercase, hyphens. This is how users invoke the agent (@code-reviewer). |
93+
| `description` | ✅ Yes | "Reviews code for bugs and best practices." | One-liner shown in the @ menu. |
94+
| `target` | ❌ Optional | `github-copilot` | Usually `github-copilot` (Copilot Chat). Defaults to auto-detection. |
95+
| `tools` | ❌ Optional | `["npm", "git", "python"]` | CLI tools/commands this agent can use. Omit for no tool access. |
96+
| `disable-model-invocation` | ❌ Optional | `false` | Set `true` if you only want manual @agent-name invocation (no auto-triggering). |
97+
| `metadata` | ❌ Optional | `owner: dev-team` | Custom key-value pairs for your team's reference. |
98+
99+
### Markdown body best practices
100+
101+
Your agent's instructions live in the Markdown. Include these sections:
102+
103+
- **# Persona** — Who is this agent? What's their specialty?
104+
- **# Boundaries** — What's off-limits? Which files are safe to edit?
105+
- **# Commands** — What CLI commands should the agent know about and use?
106+
- **# Code Style** — Preferences for naming, formatting, patterns.
107+
- **# Examples** — Real sample inputs and outputs so Copilot knows what "good" looks like.
108+
109+
## Step-by-step: create your first agent
110+
111+
Let's build a **"code-reviewer" agent** as an example. This agent will review pull requests and suggest improvements.
112+
113+
### Step 1: Create the file
114+
115+
In your repo, create `.github/agents/code-reviewer.agent.md`:
116+
117+
```bash
118+
mkdir -p .github/agents
119+
touch .github/agents/code-reviewer.agent.md
120+
```
121+
122+
### Step 2: Start with frontmatter
123+
124+
```yaml
125+
---
126+
name: code-reviewer
127+
description: "Reviews pull requests for code quality, bugs, and best practices."
128+
target: github-copilot
129+
tools:
130+
- git
131+
- npm
132+
disable-model-invocation: false
133+
metadata:
134+
owner: dev-team
135+
version: "1.0"
136+
---
137+
```
138+
139+
This tells Copilot:
140+
- The agent is called `@code-reviewer`
141+
- It reviews code for quality and bugs
142+
- It can use `git` and `npm` commands
143+
- It's enabled for auto-invocation (e.g., when someone asks for a review)
144+
145+
### Step 3: Write the persona
146+
147+
```markdown
148+
# Persona
149+
150+
You are an experienced senior engineer with 10+ years of code review experience. Your job is to:
151+
152+
1. **Find bugs** before they reach production
153+
2. **Suggest improvements** using best practices from our codebase
154+
3. **Mentor** junior engineers through constructive feedback
155+
4. **Enforce standards** without being pedantic
156+
157+
Your tone is friendly, specific, and actionable—never vague or dismissive.
158+
```
159+
160+
### Step 4: Set boundaries
161+
162+
```markdown
163+
# Boundaries
164+
165+
- **Only review code changes**, not documentation (unless asked)
166+
- **Don't suggest refactors** unless they fix a real issue or block understanding
167+
- **Don't approve PRs** with failing tests or unresolved TODOs
168+
- **Never** modify code directly—only suggest patterns and explain the "why"
169+
- **Focus on logic, security, and maintainability**—not whitespace or minor style
170+
171+
## Files you CAN review
172+
- `src/**/*.ts` and `src/**/*.js` — application code
173+
- `lib/**/*.ts` — shared libraries
174+
- Tests in `__tests__/`
175+
176+
## Files you should NOT touch
177+
- Configuration files (`webpack.config.js`, `.eslintrc`, etc.)
178+
- Generated code in `dist/` or `build/`
179+
- Third-party dependencies in `node_modules/`
180+
```
181+
182+
### Step 5: Add a checklist
183+
184+
```markdown
185+
# Code review checklist
186+
187+
When reviewing, use this checklist:
188+
189+
1. **Correctness?**
190+
- Does the code do what the PR description says?
191+
- Are there edge cases not handled?
192+
193+
2. **Tests?**
194+
- Are there tests for the new code?
195+
- Do they cover happy path AND error cases?
196+
- Do all tests pass locally?
197+
198+
3. **Performance & security?**
199+
- Any obvious performance issues?
200+
- Are external inputs validated?
201+
- No hardcoded secrets or sensitive data?
202+
```
203+
204+
### Step 6: Add examples
205+
206+
```markdown
207+
# Example review
208+
209+
## Good response format
210+
211+
### ✅ The Good
212+
- Function `calculateDiscount()` is clear and handles edge cases well
213+
- Tests cover both happy path and boundary conditions
214+
- Style matches the rest of the codebase
215+
216+
### 🔍 Questions
217+
- Line 42: Why convert to string here instead of keeping it as a number?
218+
- Is there a test for the negative discount scenario?
219+
220+
### 💡 Suggestion
221+
Consider extracting the validation logic on line 50 into a separate `validateRange()` helper. It would be reusable and easier to test.
222+
223+
## What NOT to do
224+
- Don't just say "looks good" — be specific
225+
- Don't rewrite code unless asked; suggest patterns instead
226+
- Don't approve PRs with failing tests
227+
```
228+
229+
### Step 7: Commit and test
230+
231+
```bash
232+
git add .github/agents/code-reviewer.agent.md
233+
git commit -m "Add code-reviewer agent for PR reviews"
234+
git push
235+
```
236+
237+
Now in Copilot Chat, type `@code-reviewer` and your agent appears. Try asking:
238+
239+
```
240+
@code-reviewer Please review this PR: [paste code changes]
241+
```
242+
243+
## Real-world example from this repository
244+
245+
This repository uses a custom agent called "Squad" for team coordination. You can see it at `.github/agents/squad.agent.md`. It's a more advanced example showing:
246+
247+
- Multi-line frontmatter with metadata
248+
- Detailed persona and responsibilities
249+
- Complex boundaries and refusal rules
250+
- Custom instructions for different session phases
251+
252+
Browse it for inspiration on structuring larger agents.
253+
254+
## Common agent ideas for your team
255+
256+
Here are agents other teams have found useful:
257+
258+
| Agent | Role | Good for |
259+
|-------|------|----------|
260+
| **code-reviewer** | Senior engineer reviewing code | Pull request reviews, quality gates |
261+
| **docs-writer** | Technical writer | Creating/updating documentation |
262+
| **test-writer** | QA engineer | Writing unit and integration tests |
263+
| **database-expert** | DBA/data engineer | Schema design, query optimization |
264+
| **security-auditor** | Security engineer | Vulnerability scanning, threat modeling |
265+
| **performance-tuner** | Optimization specialist | Profiling, caching, load testing |
266+
| **accessibility-checker** | A11y specialist | WCAG compliance, screen reader testing |
267+
268+
## How agents differ from other customizations
269+
270+
| Feature | Global Instructions | Skills | Agents |
271+
|---------|-------|--------|--------|
272+
| **Scope** | Applies to all Copilot interactions in the repo | Pulled in when relevant to the task | Activated by name in chat |
273+
| **How to invoke** | Automatic (always active) | Mentioned in prompts ("use the pr-ready skill") | `@agent-name` in chat |
274+
| **Best for** | Project-wide standards (naming, architecture, coding style) | Detailed, repeatable workflows (testing, deployment, release notes) | Specialized personas with boundaries (reviewers, writers, auditors) |
275+
| **Transparency** | Hidden from users | Discoverable via docs/prompts | Visible in @ menu |
276+
277+
## Pro tips
278+
279+
- 🎯 **Be specific in descriptions** — The one-liner should tell teammates exactly when to use this agent.
280+
- 🚫 **Set clear boundaries** — Tell the agent what it should NOT touch. Security and stability depend on this.
281+
- 🔧 **List tools explicitly** — Only grant access to tools the agent needs. This keeps scope tight and safe.
282+
- 📖 **Include real examples** — Show Copilot what good code review (or documentation, or tests) looks like from your project.
283+
- 🔄 **Version your agents** — If you update an agent significantly, consider adding a version comment at the top.
284+
- 🤝 **Share with your team** — Commit agents to your repo so everyone uses the same specialist.
285+
286+
## What's next?
287+
288+
Now that you understand agents, you can:
289+
290+
1. **Create 2–3 agents** for your team's most common workflows.
291+
2. **Combine with skills** — Have an agent that orchestrates a skill (e.g., "security-auditor" calls your "security-scan" skill).
292+
3. **Integrate with MCP** — If you have the [GitHub MCP server](https://github.com/github/github-mcp-server), agents can fetch live PR data, workflow logs, and more.
293+
4. **Share organization-wide** — Move agents to `.github-private/agents/` so all your org's repos can use them.
294+
295+
## Learn more
296+
297+
For detailed documentation and examples, see these official resources:
298+
299+
- **[GitHub Docs: Creating custom agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)** — Official guide and configuration reference
300+
- **[How to write a great .agent.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)** — Lessons from 2,500+ agent examples
301+
- **[Copilot agents overview](https://docs.github.com/en/copilot/concepts/agents)** — Understand agents, skills, and customization options
302+
303+
## Related reading in this series
304+
305+
This is Part 1 of the **Copilot Customization** series. Check out:
306+
307+
- **[Level Up GitHub Copilot with copilot-instructions.md](/tips/copilot-instructions-md)** — Project-wide instructions that apply to all Copilot interactions
308+
- **[Create Your First GitHub Copilot Skill](/tips/create-your-first-github-copilot-skill)** — Reusable, step-by-step playbooks for common workflows
309+
310+
All three approaches—instructions, skills, and agents—work together to create a tailored Copilot experience for your team.

0 commit comments

Comments
 (0)