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

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.

---
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, 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 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, 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". 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, an agent may include a next_agent field in its response payload:

{
  "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 serves as the definitive reference template for this process.

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

---
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 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}