What is an Agent

Agents are specialized AI assistants that run in separate context windows, enabling focused work without polluting your main conversation. Learn when to use agents versus tools, and how context isolation drives their core benefits.

An agent is a configured AI context. It combines a role definition, relevant context files, tool access, and behavioral instructions.

Aspect	Description	Example
Role	What the agent is	"You are an onboarding assistant for this Java monorepo"
Context	What it knows	AGENTS.md, copilot-instructions.md, README
Tools	What it can do	File read/write, bash, web search, MCP servers
Behavior	How it acts	Always run tests before suggesting a PR

When to create an agent: when the same role + context + behavior will be used repeatedly across your team.

Anatomy

Agents are packaged as markdown files with YAML frontmatter, defining their capabilities, constraints, and behavior.

Structure of an agent

Agents are defined as markdown files with YAML frontmatter:

text

.claude/agents/                   # For Github Copilot ~/.github/agents/
    code-reviewer/
    ├── code-reviewer.md          # Agent definition (required)
    └── scripts/                  # Validation scripts (optional)
        └── validate.sh

Example agent file (Claude Code)

markdown

---
name: api-developer
description: Build API endpoints following team conventions. Use when implementing REST APIs or microservices.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
memory: project
permissionMode: acceptEdits
skills:
  - api-conventions
  - error-handling-patterns
mcpServers:
  - github
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

You are an API development specialist. When invoked:
1. Review preloaded skills for team conventions
2. Implement endpoints following established patterns
3. Use GitHub tools to reference related PRs
4. Use Playwright tools to test endpoints in browser
5. Include proper error handling and validation

Always follow the conventions from your preloaded skills.

Example agent file (GitHub Copilot)

markdown

---
description: "Use when: creating user stories, writing feature requests, defining acceptance criteria, describing new stories, PM story grooming, backlog refinement, story templates, feature specifications, requirement definitions"
name: "Story Writer"
tools: [read, search, edit]
argument-hint: "Briefly describe the feature, change, or requirement you want to document as a story"
---

You are a **senior product manager** specializing in translating business requirements into well-structured, unambiguous user stories that engineers can implement without guesswork.

Note: Agents from the GitHub Copilot extension in VS Code use a different frontmatter schema than Claude Code agents.

Key frontmatter fields

Field	Purpose	Example
`name`	Unique identifier	`code-reviewer`
`description`	When Claude should delegate to this agent	"Use proactively after..."
`tools`	Which tools agent can access	`Read, Grep, Glob, Bash`
`model`	Model to use (`sonnet`, `opus`, `haiku`)	`sonnet`
`memory`	Persistent memory scope (`user`, `project`)	`project`
`permissionMode`	Permission handling (`default`, `auto`, `plan`)	`auto`
`skills`	Preload skills into agent's context	`api-conventions`
`mcpServers`	MCP servers available to this agent	`github, slack`

When to Use Agents

Scenario	Use Agent	Why
Running tests with verbose output	Yes - isolate in subagent	Keeps test logs out of main context
Parallel research on multiple modules	Yes - spawn multiple agents	Each explores independently, returns summary
Enforcing read-only database queries	Yes - restrict tools with hooks	Validate commands before execution
Quick code change in current context	No - work in main conversation	No need for context isolation
Iterative refinement with user	No - stay in main thread	Frequent back-and-forth benefits from shared state

Agent Types & Examples

Built-in agents (Claude Code)

Name	Purpose	Tools	Context Strategy
Explore	Fast codebase search	Read-only	Isolates exploration from main
Plan	Research for planning mode	Read-only	Prevents infinite nesting
general-purpose	Complex multi-step tasks	All tools	Handles exploration + modification

Custom agent examples

Name	Purpose	Tools	Context Strategy
code-reviewer	Review code quality	Read, Grep, Glob, Bash	Read-only review without edits
tester	Run tests and report failures	Bash, Read, Grep	Isolates verbose test output

What is an Agent ​

Anatomy ​

Structure of an agent ​

Example agent file (Claude Code) ​

Example agent file (GitHub Copilot) ​

Key frontmatter fields ​

When to Use Agents ​

Agent Types & Examples ​

Built-in agents (Claude Code) ​

Custom agent examples ​

References ​