# How Specialized Agent Personas Are Defined in Claude Plugins

> Learn how Claude plugins define specialized agent personas using manifest files. Discover how to declare distinct characters with specific names, descriptions, and persona text for your AI agents.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-08-28

---

**Claude plugins define specialized agent personas through manifest files ([`plugin.yaml`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.yaml) or [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json)) that declare distinct characters with specific names, descriptions, persona text, and allowed tools.**

In the `anthropics/claude-plugins-community` repository, plugins implement specialized agent personas to provide Claude with pre-configured identities that govern tone, expertise, and operational boundaries. These personas are declared at the manifest level and injected into the system prompt when specific agents are invoked via the `agent_name` parameter.

## The Agent Manifest Structure

Each specialized agent persona originates in the plugin's manifest file. Whether using YAML or JSON format, the manifest contains an `agents` array where each object defines a specific character.

The schema requires five key fields:

- **name** – A unique identifier referenced in skill invocations (e.g., `quickdesign`)
- **description** – Human-readable summary displayed in the UI when suggesting agents
- **persona** – Free-form text shaping the model's tone, style, and operational assumptions
- **tools** – Array of permitted tool identifiers (e.g., `WebSearch`, `RunBash`, `ReadFile`)
- **default** (optional) – Boolean marking which agent loads when no explicit `agent_name` is specified

According to the repository's validation policy in [`.github/actions/scan-plugins/policy/prompt.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/scan-plugins/policy/prompt.md), these definitions must declare tool permissions explicitly to enforce safety and cost controls.

## Defining Persona Behavior and Constraints

The `persona` field contains system prompt text that fundamentally alters how Claude approaches tasks. This text supports role-playing cues, cardinal rules, and behavioral constraints.

In [`/quickdesign/plugin.yaml`](https://github.com/anthropics/claude-plugins-community/blob/main//quickdesign/plugin.yaml), the QuickDesign agent demonstrates cost-conscious behavior through its persona definition:

```yaml
persona: |
  You are a creative assistant who always:
  * respects the user's budget
  * asks for confirmation before spending credits
  * prefers the `seedance-2.0-r2v` model for UGC videos unless the user explicitly asks otherwise

```

This persona injection ensures the agent checks credits before executing expensive operations, a constraint enforced at the system level rather than requiring repeated user prompting.

## Tool Access Control and Limitations

The `tools` array acts as an allowlist, restricting which capabilities the specialized agent can invoke. This security boundary prevents personas from accessing inappropriate functions.

Common tool identifiers referenced in the codebase include:

- `WebSearch` – Internet retrieval capabilities
- `AskUserQuestion` – Interactive clarification requests
- `RunBash` – Shell command execution
- `ReadFile` – File system read operations
- `WriteFile` – File system write operations

For example, the `tres_reporter` agent in the finance plugin only receives `["ReadFile", "WriteFile", "AskUserQuestion"]`, ensuring it cannot execute arbitrary bash commands while processing sensitive financial data.

## Implementation Examples

### YAML Format (QuickDesign Plugin)

The following definition from [`/quickdesign/plugin.yaml`](https://github.com/anthropics/claude-plugins-community/blob/main//quickdesign/plugin.yaml) illustrates a complete agent specification with multiple personas:

```yaml

# /quickdesign/plugin.yaml

name: quickdesign
description: QuickDesign media-generation plugin
version: 1.0
agents:
  - name: quickdesign
    description: Generate images and videos via QuickDesign CLI
    persona: |
      You are a creative assistant who always:
      * respects the user's budget
      * asks for confirmation before spending credits
      * prefers the `seedance-2.0-r2v` model for UGC videos unless the user explicitly asks otherwise
    tools: [WebSearch, AskUserQuestion, RunBash]
    default: true

  - name: quickdesign_admin
    description: Advanced admin operations (model registry queries, cost calculations)
    persona: |
      You are an expert who knows the current model registry state.
      Provide accurate cost estimates and suggest alternative models when appropriate.
    tools: [RunBash, ReadFile]

```

### JSON Format (Tres Finance Plugin)

Alternative plugins use JSON manifests located at paths like [`/tres-finance-plugin/manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main//tres-finance-plugin/manifest.json):

```json
{
  "name": "tres-finance",
  "description": "Finance-focused plugins for TREs",
  "agents": [
    {
      "name": "tres_reporter",
      "description": "Creates financial reports from uploaded data",
      "persona": "You are a meticulous financial analyst. Double-check all numbers and cite sources.",
      "tools": ["ReadFile", "WriteFile", "AskUserQuestion"]
    },
    {
      "name": "tres_auditor",
      "description": "Audits data quality and suggests improvements",
      "persona": "You act as a senior auditor, flagging inconsistencies and recommending clean-up steps.",
      "tools": ["ReadFile", "AskUserQuestion"]
    }
  ]
}

```

## Runtime Invocation and Skill Integration

When a user invokes a skill specifying `agent_name: quickdesign`, Claude performs three operations:

1. Locates the manifest definition matching the identifier
2. Injects the `persona` text into the system prompt, establishing behavioral constraints
3. Restricts tool availability to the declared `tools` array

The skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file (e.g., [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md)) then provides the concrete execution rules, creating a layered architecture where the manifest defines *who* the agent is, while the skill file defines *what* the agent does.

## Summary

- Specialized agent personas in Claude plugins are declared in [`plugin.yaml`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.yaml) or [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json) files within the `agents` array.
- Each persona requires a `name`, `description`, `persona` text, and `tools` allowlist to function.
- The `persona` field supports complex behavioral instructions, including cost controls and role-playing cues.
- Tool restrictions enforce security boundaries, preventing agents from accessing unauthorized capabilities.
- The `default` flag designates which agent loads when no explicit `agent_name` is provided in the skill invocation.

## Frequently Asked Questions

### What file formats support agent persona definitions?

Claude plugins accept both YAML and JSON formats for manifest files. The community repository shows examples of [`plugin.yaml`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.yaml) (YAML) and [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json) (JSON) implementations, both supporting identical `agents` array schemas with `name`, `description`, `persona`, and `tools` fields.

### Can a plugin have multiple specialized agent personas?

Yes. A single manifest file can declare multiple agent objects within the `agents` array. For instance, the QuickDesign plugin defines both a standard `quickdesign` agent for media generation and a `quickdesign_admin` agent for advanced operations, each with distinct persona text and tool permissions.

### How does the persona text affect Claude's behavior?

The `persona` text is injected into the system prompt when the agent is invoked, establishing persistent behavioral constraints. Unlike user-level instructions that may be forgotten during long conversations, persona definitions remain active throughout the interaction, enforcing rules like budget checks or tone requirements.

### What validation exists for agent definitions?

The repository employs automated scanning via [`.github/actions/scan-plugins/policy/prompt.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/scan-plugins/policy/prompt.md) to validate that agent definitions include proper tool declarations and safety constraints. This validation ensures that specialized agent personas cannot access tools beyond their declared scope and that all required fields are present in the manifest.