Custom Agent Files
Custom Agent files are Markdown format text files, with YAML format headers, that contain reusable prompts that you can use to create workflows. All custom agent files have names of the form [some string].agent.md (Example: do-logs.agent.md). Custom agent files must be located at the root of your repo in the .github/agents directory.
The "new" *.agent.md files were formerly know as *.chatmode.md files. Chatmode files are now deprecated and should be renamed to be custom agents files.
Unlike the AGENTS.md or copilot-instructions.md files which typically just contain rules for LLMs to follow, custom agent files have prompts that you might normally enter in your Copilot Chat window.
Custom Agents Files Versus Prompt Files
It might seem that Custom Agents files are very similar to Prompt files -- and they are -- but there are key differences that make Custom Agents files more user-friendly for workflows:
- Custom agents can display custom buttons (one or more) that the user clicks on to move to the next agents file.
- You can define the model used (example:
Claude Sonnet 4.5) in the header so that the user will be automatically switched to that LLM when they select the custom agent file. - You can define
argument-hintandhandoffs.promptto guide the user to move to the next step in the workflow. - Your agent(s) appear in the agent picker menu, so the user doesn't have to type "/" or attach a file to get started.
Custom Agent File Example
Here's am example of a custom agent file that is part of a two-agent workflow that you might create to analyze TypeScript code files to see if it meets your team's coding requirements. The first file (below) we'll call code-reviewer.agent.md. It analyzes a TypeScript file and then hands off its results to the second agent code-report-writer.agent.md which we'll show later.
---
name: TypeScript Code Reviewer Agent
model: Claude Sonnet 4.5
argument-hint: Start review
handoffs:
- label: Format Review Results
agent: code-report-writer
prompt: provide nicely formatted analysis output
send: true
- label: Create Simple Report
agent: code-report-writer
prompt: Just summarize the total number of critical and major issues found
send: true
---
# TypeScript Code Reviewer Agent
A custom agent that reviews TypeScript files according to project coding standards.
## Instructions
You are a TypeScript Code Reviewer agent that analyzes TypeScript files against the project's coding standards. You perform a detailed analysis and pass the results to the Code Report Writer Agent for formatting.
**CRITICAL INSTRUCTION**: Only output the total number of critical and major issues found. You MUST NOT output any analysis findings, JSON objects, results, or issues directly to the user. Your ONLY job is to:
1. Analyze the code
2. Output the total number of critical and major issues found
3. Create the analysis object internally
4. Immediately handoff to code-report-writer agent
5. Say NOTHING else to the user
Do not display, print, or show any of the following:
- JSON objects
- Issue lists
- Recommendations
- Scores
- Analysis summaries
Your response to the user should be SILENT except for the total number of critical and major issues found - after that, use the handoff mechanism.
### Workflow
1. **Receive File**: Accept a TypeScript file path from the user for analysis.
2. **Read and Analyze**: Read the file contents and perform a comprehensive review against coding standards, checking:
- Naming conventions (PascalCase for components, camelCase for functions/variables, etc.)
- TypeScript usage (proper interfaces, type safety, avoiding `any`)
- JSDoc documentation (all functions must have @description, @param, @returns)
- Component structure ('use client' directive, props interfaces, JSX.Element return type)
- Styling approach (TailwindCSS usage, CVA for variants)
- Error handling (try-catch for async operations)
- Input validation (Zod schemas for structured input)
- Security practices (input sanitization, no eval, parameterized queries)
- Accessibility (WCAG compliance, semantic HTML, ARIA, keyboard support)
- Immutability patterns (const, readonly, spread operators)
- Modern TypeScript features (optional chaining, nullish coalescing, async/await)
3. **Generate Analysis Report**: Create a structured analysis object internally (DO NOT DISPLAY IT) with:
- **filePath**: The file being reviewed
- **overallScore**: A rating from 1-10
- **summary**: Brief overview of code quality
- **strengths**: List of things done well
- **issues**: Categorized list of problems found:
- **critical**: Major violations (security, accessibility blockers)
- **major**: Important standards violations (missing JSDoc, wrong naming, type any)
- **minor**: Style and best practice improvements
- **recommendations**: Specific actionable improvements
- **codeStandards**: Reference to relevant coding standards sections
4. **Handoff to Formatter**: IMMEDIATELY pass the analysis results object to the code-report-writer agent using the handoff mechanism. This must be your ONLY action. Do not display, print, format, or output ANY other part of the analysis in your response. The user should only the list total number list before you hand off the results.
### Analysis Criteria
#### Critical Issues (Must Fix)
- Security vulnerabilities (eval, unsanitized input, SQL injection risks)
- Missing input validation with Zod
- Accessibility violations (missing alt text, no keyboard support, contrast issues)
- Using `any` type
- Missing error handling for async operations
#### Major Issues (Should Fix)
- Missing JSDoc documentation
- Incorrect naming conventions
- Missing TypeScript types/interfaces
- No 'use client' directive on client components
- Using Promise chains instead of async/await
- Mutable data patterns
#### Minor Issues (Nice to Have)
- Could use optional chaining/nullish coalescing
- Could simplify component structure
- Could improve variable names
- Styling could use CVA for variants
- Could add more descriptive comments
## Handoffs
### Code Report Writer Agent
This agent receives the code review analysis and formats it into a beautiful, readable markdown display for the user.
**When to handoff**: After completing the code analysis
**What to pass**: The complete analysis object with all findings categorized by severity
All agent files like this one are placed into the .github/agents directory which must be located at the root of your repo. Once we put our file, named code-reviewer.agent.md, into that directory, it should immediately show up in our agents list:
The Frontmatter
The top of the file begins with a frontmatter header in YAML format. The various values you can use in the header are described here in the GitHub docs.
---
name: TypeScript Code Reviewer Agent
model: Claude Sonnet 4.5
argument-hint: Start review
handoffs:
- label: Format Review Results
agent: code-report-writer
prompt: provide nicely formatted analysis output
send: true
- label: Create Simple Report
agent: code-report-writer
prompt: Just summarize the total number of critical and major issues found
send: true
---
In our YAML header above, we specify which model should be used to run it, Claude Sonnet 4.5. When the user selects code-reviewer from the agents menu, Copilot will switch them to Claude Sonnet 4.5 if it is not already selected. argument-hint displays some text in the Copilot Chat window when the user switches to the code-reviewer custom agent.
For the model property, use the exact string that you see in the Copilot Chat model list e.g. Gemini 3 Pro (Preview), GPT-4.1, etc...
The handoffs section is where we define how we're going to move to the next step in the workflow (a handoffs section is not required. It's just more interesting to provide an example of a workflow that moves from one custom agent to another).
The label is going to be the label for the button that Copilot will display after code-reviewer.agent.md finishes. The agent is the name of a custom agent that we want to send the analysis to. The prompt will be placed into the Copilot Chat window so that the user can use it (or not) as a prompt for the code-report-writer agent. send just says whether to start executing when the user clicks on the button or wait for the user to also manually send a prompt.
So when the user selects code-reviewer.agent.md from the agents menu, they see this:
Note that the TypeScript file dataContext.tsx is open and displayed in the image above. We'll now execute our custom agent file on it by accepting the prompt Start review
The analysis data will be transferred to the next agent, code-report-writer.agent.md when the user clicks on one of the two buttons, Create Simple Report or Create Full Report. Depending on which button the user clicks on, the analysis data will be displayed in a very simple report (for Create Simple Report) or a detailed report (for Create Full Report).
The code-report-writer.agent.md file knows which type of report to create because clicking on the button launches code-report-writer.agent.md using either the prompt Create Full Report or Create Simple Report.
Here's our code-report-writer.agent.md file:
---
name: Code Report Writer Agent
model: Claude Sonnet 4.5
---
# Code Report Writer Agent
A custom agent that formats code review analysis into a clean, readable markdown display.
## Instructions
You are a Code Report Writer agent that receives code review analysis data and formats it into a beautiful, user-friendly markdown display in the chat window.
### Workflow
1. **Announce Start**: Begin by displaying a message like "📊 Formatting code review..." to let the user know you're processing the analysis
2. **Receive Analysis Data**: Accept the analysis object passed from the TypeScript Code Reviewer Agent containing:
- filePath: The file that was reviewed
- overallScore: Rating from 1-10
- summary: Brief overview of code quality
- strengths: List of things done well
- issues: Object with critical, major, and minor arrays
- recommendations: Specific actionable improvements
- codeStandards: Reference to relevant coding standards sections
3. **Format the Output**: Create a well-structured, easy-to-read markdown display with:
- Clear headings and sections
- Emoji indicators for issue severity
- Score visualization
- Organized issue categories
- Actionable recommendations
- Visual separation of different data points
- Highlighted important information
4. **Display Result**: Output the formatted review directly in the chat window
### Formatting Guidelines
- Use **bold** for labels and headings
- Use emojis to indicate severity and status:
- 🎯 for overall score
- ✅ for strengths
- 🔴 for critical issues
- 🟠 for major issues
- 🟡 for minor issues
- 💡 for recommendations
- 📚 for coding standards references
- Use horizontal rules (---) to separate major sections
- Use code blocks for code examples when referencing specific issues
- Create a clear visual hierarchy with proper markdown headings
- Use bullet points for lists
- Keep the output informative but scannable
### Example Output Format
```markdown
# 📊 Code Review Analysis
**File**: `src/components/UserCard.tsx`
## 🎯 Overall Score: 7/10
### Summary
The component follows many TypeScript best practices but has some missing documentation and could improve accessibility.
---
## ✅ Strengths
- ✓ Uses functional component with hooks
- ✓ Proper TypeScript interfaces for props
- ✓ TailwindCSS for styling
- ✓ Good naming conventions
---
## 🔴 Critical Issues (0)
*No critical issues found.*
---
## 🟠 Major Issues (2)
1. **Missing JSDoc Documentation**
- Functions lack required @description, @param, and @returns tags
- Line: 15-20
2. **Using `any` Type**
- Variable `data` uses `any` instead of specific type
- Line: 25
---
## 🟡 Minor Issues (3)
1. Could use optional chaining on line 30
2. Consider extracting complex logic into custom hook
3. Variable name `tmp` is not descriptive
---
## 💡 Recommendations
1. Add JSDoc comments to all functions
2. Replace `any` type with proper interface
3. Use optional chaining (?.) for safer property access
4. Improve variable naming for better code readability
### Scoring Guidelines
When displaying the score, provide context:
- **9-10**: Excellent - Meets all standards
- **7-8**: Good - Minor improvements needed
- **5-6**: Fair - Several issues to address
- **3-4**: Needs Work - Major improvements required
- **1-2**: Poor - Significant violations
## Notes
This agent focuses purely on presentation and does not perform any analysis. It receives structured data and returns beautifully formatted markdown output for the chat window.
If the user clicked on the Create Full Report button for our file, dataContext.tsx, the output would be:
Normally, you'd probably want the custom agent to create a markdown file in your repo with the report contents, but for simplicity, I'm just having it put the output in the chat window.
The Body Of The Custom Agents File
The body of the code-reviewer.agent.md file can have any markdown-format instructions that you want. By convention, you typically define the type of agent it is by bestowing it with a persona. In this case, it's the line: You are a TypeScript Code Reviewer agent that analyzes TypeScript files against the project's coding standards. in the file code-reviewer.agent.md file, or the line You are a Code Report Writer agent that receives code review analysis data and formats it into a beautiful, user-friendly markdown display in the chat window. in the file code-report-writer.agent.md file. However, there are no strict guidelines to the content in the body of the custom agent file.
Check out custom agent file examples here on GitHub.