# How Agent Definitions Work in Claude Plugins: The Complete Technical Guide

> Learn how agent definitions work in Claude plugins. Discover how Markdown and YAML define reusable AI agents that trigger automatically based on user requests. Get the complete technical guide.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: deep-dive
- Published: 2026-03-13

---

**Claude plugins use Markdown files with YAML front-matter to define reusable AI agents that trigger automatically when user requests match specific semantic phrases.**

The `anthropics/claude-plugins-official` repository demonstrates how Claude treats agents as modular micro-services. Each agent definition lives in a plain-text file that combines metadata with a static system prompt, enabling the runtime to spawn sandboxed sub-agents on demand.

## What Are Claude Plugin Agents?

Agents in Claude plugins are self-contained AI workers that handle specialized tasks. According to the source code, an agent consists of a unique identifier, a trigger description, an optional model specification, and a complete system prompt. The Claude runtime discovers these agents through a convention-based file structure and invokes them either automatically through intent parsing or explicitly by name.

## Agent Definition File Structure

Every agent follows a strict Markdown format located at `plugins/<plugin-name>/agents/<agent-name>.md`. The file separates configuration from instructions using YAML front-matter delimited by triple dashes.

```markdown
---
name: code-reviewer
description: |
  Use this agent when the user asks to review code,
  wants a quality check before a PR, or mentions
  "code review".
model: sonnet
color: red
tools: ["Read", "Write", "WebFetch"]
---
You are an expert code reviewer focused on security vulnerabilities...

```

The front-matter fields serve distinct purposes:
- **name**: The unique identifier users can reference explicitly
- **description**: The trigger cue that begins with "Use this agent when..." for natural language matching
- **model**: The Claude model variant (defaults to `inherit` if omitted)
- **color**: A UI hint for the console display (no execution impact)
- **tools**: An allowlist of capabilities the agent may invoke

Everything after the closing `---` becomes the agent's static system prompt—the complete instruction set the model receives upon invocation.

## How Claude Discovers and Loads Agents

The runtime loads agents through a two-phase discovery process starting from the plugin manifest. In [`plugins/pr-review-toolkit/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/pr-review-toolkit/.claude-plugin/plugin.json), the manifest declares the plugin metadata, prompting the runtime to scan for agents inside that plugin's directory.

The loading sequence follows these steps:

1. **Manifest parsing**: The runtime reads [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/plugin.json) to identify active plugins
2. **Directory traversal**: The system walks the `agents/` subdirectory seeking `*.md` files
3. **Front-matter extraction**: Each file's YAML block is parsed to register the agent's identifier and description trigger
4. **Prompt storage**: The remaining Markdown content is stored verbatim as the system prompt

Agents are maintained in an internal registry available for the duration of the Claude session.

## Trigger Mechanisms and Execution

Claude employs dual triggering mechanisms to invoke agents based on user intent.

**Implicit triggers** occur when the natural language parser matches user utterances against agent descriptions. For example, saying "review my code" matches the description in [`plugins/pr-review-toolkit/agents/code-reviewer.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/pr-review-toolkit/agents/code-reviewer.md), automatically spawning that agent.

**Explicit triggers** happen when users directly reference an agent by its `name` field, such as "run the `code-reviewer` agent on [`src/main.py`](https://github.com/anthropics/claude-plugins-official/blob/main/src/main.py)". The runtime performs a direct registry lookup and passes any additional arguments as input variables.

When triggered, the runtime spawns a sub-agent job that:
- Sets the specified model (or inherits the parent session's model)
- Grants only the tools listed in the `tools` array
- Supplies the complete system prompt from the Markdown body
- Returns output to the main Claude session upon completion

## Agent Chaining and Multi-Step Workflows

Agents can orchestrate complex pipelines by emitting structured output that references other agents. As implemented in [`plugins/feature-dev/agents/code-architect.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/feature-dev/agents/code-architect.md), an agent may include a `next_agent` field in its response payload:

```json
{
  "next_agent": "code-reviewer",
  "input": { "scope": "generated files" }
}

```

Claude's runtime detects this directive and automatically spawns the specified agent, creating sequential workflows such as code exploration followed by architecture design and final review.

## Tool Sandboxing and Security Enforcement

Each agent operates within a capability sandbox defined by its `tools` array. The runtime enforces strict boundaries preventing agents from invoking unlisted tools. For instance, the `comment-analyzer` agent in the PR review toolkit receives only `Read` and `Grep` permissions, while `code-reviewer` receives `WebFetch` for vulnerability lookups. This principle of least privilege ensures agents perform only their designated operations.

## Creating Custom Agent Definitions

To extend a plugin with new capabilities, developers create Markdown files following the established schema. The [`plugins/plugin-dev/agents/agent-creator.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/agents/agent-creator.md) serves as the definitive reference template for this process.

Here is a minimal working example for a custom "todo-linter" agent:

```markdown
---
name: todo-linter
description: |
  Use this agent when the user wants to validate TODO comments in the codebase,
  asks "find all TODOs", or wants to ensure they follow the project's format.
model: inherit
color: cyan
tools: ["Read", "Grep"]
---
You are a diligent linter that scans the entire repository for TODO
comments. Follow these steps:

1. Run a `grep -R` for the pattern `TODO:` across the codebase.
2. For each match, verify that it conforms to the project style:
   - Must include a ticket number (`TODO[#1234]:`).
   - Must be accompanied by an owner name.
3. Produce a JSON array of violations.

```

Place this file in your plugin's `agents/` directory and reload the plugin. Claude will register the agent automatically and begin matching user requests against your description trigger.

## Summary

- Agent definitions reside in `plugins/<name>/agents/<agent>.md` files using YAML front-matter for metadata and Markdown for system prompts
- The [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/plugin.json) manifest triggers the runtime to discover and register agents from the `agents/` directory
- Descriptions must start with "Use this agent when..." to enable automatic intent-based triggering
- The `tools` array enforces strict capability sandboxes, limiting agent access to specific operations
- Agents support chaining through structured output directives like `next_agent`, enabling multi-step automation pipelines
- New agents require only a single Markdown file following the schema demonstrated in [`code-reviewer.md`](https://github.com/anthropics/claude-plugins-official/blob/main/code-reviewer.md) and [`agent-creator.md`](https://github.com/anthropics/claude-plugins-official/blob/main/agent-creator.md)

## Frequently Asked Questions

### How does Claude know when to activate a specific agent?

Claude matches user requests against the `description` field in each agent's YAML front-matter. The description functions as a trigger cue—when the natural language parser detects semantic alignment between the user's request and the description text (or when the user explicitly names the agent), the runtime spawns the corresponding sub-agent.

### What file format do Claude plugin agents use?

Agents use standard Markdown files with YAML front-matter between triple-dash delimiters. The front-matter contains configuration metadata (`name`, `description`, `model`, `color`, `tools`), while the remainder of the file serves as the static system prompt provided to the model upon execution.

### Can agents in Claude plugins access any tool by default?

No. Agents operate within strict capability boundaries defined by the `tools` array in their front-matter. The runtime enforces this allowlist, preventing the agent from calling any tool not explicitly granted. For example, an agent with `tools: ["Read", "Grep"]` cannot perform web searches or file writes.

### What is the difference between the `name` and `description` fields in an agent definition?

The `name` field provides a unique technical identifier used for explicit agent invocation and programmatic references (such as agent chaining). The `description` field provides natural language trigger phrases that Claude's intent parser uses to automatically detect when to launch the agent based on conversational context.