How Specialized Agent Personas Are Defined in Claude Plugins

Claude plugins define specialized agent personas through manifest files (plugin.yaml or 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, 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, the QuickDesign agent demonstrates cost-conscious behavior through its persona definition:

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 illustrates a complete agent specification with multiple personas:

# /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:

{
  "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 file (e.g., 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 or 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 (YAML) and 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 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.

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