# Custom Agents and Personas

> When and how to define specialized agents configured for a specific role or task. How persona definitions, scoped instructions, and the AGENTS.md pattern let you build agents that stay focused and don't overstep.

- **Source:** https://ainativesoftware.engineering/roadmap/day-4/custom-agents-and-personas
- **Site:** AI-Native Software Engineering — https://ainativesoftware.engineering/book

- **Day:** 4 · position 4 of 8
- **Reading time:** 3 minutes
- **Day overview:** [Day 4](https://ainativesoftware.engineering/roadmap/day-4.md)

When and how to define specialized agents configured for a specific role or task. How persona definitions, scoped instructions, and the AGENTS.md pattern let you build agents that stay focused and don't overstep.

## Theory

Rules give agents project-level context. Custom agents go one step further: they package a specific persona, a specific set of instructions, and a specific set of tools into a reusable configuration you can switch into with a single click.

The key insight is that different tasks need different setups. A planning agent should not be able to edit files; you want it to think and propose, not accidentally change things. A security reviewer agent should be skeptical and focused on vulnerabilities, not general coding help. A commit message generator just needs to read the diff and write one thing. When you bundle the right instructions and the right tools together, the agent is less likely to drift and more likely to be useful immediately.

### What a custom agent is made of

Custom agents are defined in a single Markdown file. In VS Code and Copilot this file has the `.agent.md` extension and lives in `.github/agents/`. In Claude Code, they live in `.claude/agents/` as regular `.md` files.

At the top you put a YAML header with the configuration:

```yaml
---
name: PR Reviewer
description: Reviews pull request diffs for bugs, security issues, and missing tests
tools: ['codebase', 'fetch']
---
```

Below the header, you write the instructions in plain Markdown. This is where you define the persona: what the agent focuses on, what it should always check, what it should never do, and how it should format its output.

### Tool scoping matters

One of the most practical things custom agents let you do is restrict which tools are available. A read-only research agent that has no ability to write files cannot accidentally break something. An implementation agent that only has editing tools and terminal access won't go off looking up unrelated documentation mid-task. Scoping tools is both a quality improvement and a safety measure.

### Handoffs

VS Code and Copilot support handoffs: after one agent finishes, it shows a button that switches to the next agent in a workflow, pre-filling the prompt with relevant context. This makes it easy to build lightweight multi-step workflows, like Plan → Implement → Review, without any custom infrastructure.

### When to build a custom agent

A custom agent is worth building when you find yourself running the same kind of task repeatedly and always giving the same setup instructions manually. If you keep writing "review this for security issues, focus on injection risks, format findings as a numbered list" in every chat, that is a custom agent waiting to be created.

**Theory resources**

- [Custom Agents in VS Code – Microsoft Docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
- [SubAgents – Cursor Docs](https://cursor.com/docs/context/subagents)
- [Sub-Agents – Claude Docs](https://code.claude.com/docs/en/sub-agents)

## Practice

Run this in a repository you already know, not a toy project.

Build a custom agent that solves a real, recurring problem in your daily work. The goal is to have something genuinely useful at the end, not a toy example.

**Step 1: Pick a problem worth automating.**

Think about tasks you do repeatedly that follow a predictable pattern. Good candidates:
- Reviewing a PR diff for a specific class of issues (security, missing tests, accessibility)
- Writing commit messages or PR descriptions from a diff
- Generating a test file for a given module following your team's conventions
- Summarizing a GitHub issue into a task breakdown
- Checking a new API endpoint against your team's API design standards

**Step 2: Design the agent before you write it.**

Answer these questions first:
- What is the single job this agent does? (One sentence)
- What tools does it need? Does it need to edit files, or just read and respond?
- What should it always do? What should it never do?
- How should it format its output?

**Step 3: Create the agent file.**

Use the format for your tool:
- VS Code / Copilot: create `.github/agents/your-agent.agent.md`
- Claude Code: create `.claude/agents/your-agent.md`
- Cursor: create a custom agent from the settings or use the `.cursor/rules/` approach with a dedicated role file

Write a tight YAML header (name, description, tools) and a clear instruction body. Keep the instructions specific: tell it what to focus on, how to structure the output, and any constraints.

**Step 4: Run it on real work.**

Use the agent on at least three real tasks, not made-up examples. For each one, note:
- Did it follow the instructions without prompting?
- Did it do something you didn't expect?
- How much editing did the output need?

**Step 5: Iterate and commit.**

Refine the instructions based on what you observed. Then commit the agent file to your repo so your team can use it too. A well-built custom agent is a shared productivity asset, not a personal configuration.

- **Previous topic:** [Skills and Commands: Reusable Patterns](https://ainativesoftware.engineering/roadmap/day-4/skills-and-commands-reusable-patterns.md)
- **Next topic:** [Rules, Skills, Commands, and Custom Agents: Knowing What to Use When](https://ainativesoftware.engineering/roadmap/day-4/rules-skills-commands-and-custom-agents-knowing-what-to-use-when.md)

---

_AI-Native Software Engineering by Alfonso Graziano (O'Reilly Media, Early Release; print edition February 2027). Every page of ainativesoftware.engineering is also served as Markdown: append `.md` to any URL. Index: https://ainativesoftware.engineering/llms.txt — whole site in one file: https://ainativesoftware.engineering/llms-full.txt._