Skip to content

Glossary

Claude Code agent

Last updated

Definition

A Claude Code agent, or custom subagent, is a Markdown file with YAML frontmatter that defines a reusable specialist, such as a code reviewer, that Claude Code can hand work to.

Also called: custom subagent, subagent definition, agent file.

The frontmatter says who the agent is and what it may do; the Markdown below it is the agent's instructions (its system prompt). Only name and description are required. The description matters most, because Claude reads it to decide when to delegate.

---
name: code-reviewer
description: Reviews a diff for bugs and missing tests. Use after changing code.
tools: Read, Grep, Glob
model: sonnet
---

Review the changes. List real problems first, each with file and line.

Optional fields include tools and disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort and isolation. When two agents share a name, the higher scope wins:

ScopeWhere
Organisation (highest)managed settings
One sessionthe --agents CLI flag
Project.claude/agents/ in the repo, usually committed for the team
Personal~/.claude/agents/, for all your projects
Plugin (lowest)an installed plugin's agents/ folder

You can use an agent by naming it in a prompt, @-mentioning it, or running a whole session as it with --agent. When it runs, it works as a subagent.

In Pairbar

The Agents tab lists every personal, project and plugin agent Claude Code would load. New agent, Improve, Turn this chat into an agent and Teach an agent from this chat open a Claude chat that writes or edits the file for you; Edit manually is a form. Add to Codex exports an agent to ~/.codex/agents/<name>.toml, and an optional dock.yaml adds groups, icons and ready-made commands. See Agents.

PERSONAL · ~/.claude/agentscode-revieweropus · read-only · 3 commandsinvestigatorsonnet · read-only · 2 commandsPROJECT · acme-web/.claude/agentsmigration-writersonnet · edits code · 1 commandPLUGINS (read-only)security-auditorinherit · read-onlyNew agent · Improvea Claude chat writes the file,following your existing agentsStartready-made commands, e.g."Review this PR: {input}"Add to Codexexports ~/.codex/agents/<name>.toml
The Agents tab grouping personal, project and plugin agents.

Frequently asked questions

Where do I put a Claude Code agent file?
In .claude/agents/ inside a repo for a project agent, or in ~/.claude/agents/ for one you want in every project.
Which frontmatter fields are required?
Only name and description. Tools, model, permission mode and the rest are optional.
Can Codex use my Claude Code agents?
Not directly; Codex defines custom agents as TOML files in ~/.codex/agents. Pairbar's Add to Codex exports a Claude agent into that format.

Related