MUST BE USED when user says 'create an agent', 'make an agent', 'new agent', 'build an agent', 'write an agent', 'add an agent', or describes agent functionality they need. Also use when editing existing agent markdown files or iterating on agent definitions. Load this skill BEFORE any agent-related work.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
references/agent-patterns.mdThis skill provides guidance for creating effective agents for Claude Code plugins.
Agents are autonomous task handlers that extend Claude Code's capabilities for complex, multi-step operations. They are invoked via the Task tool with a subagent_type parameter and run as independent subprocesses with their own context.
| Create an Agent when... | Create a Skill when... |
|---|---|
| Task requires autonomous multi-step execution | Knowledge/workflow should auto-trigger |
| User explicitly invokes via Task tool | Context should load on keyword detection |
| Subprocess isolation is beneficial | Information augments current conversation |
| Complex tool coordination needed | Procedural guidance for the main agent |
Every agent consists of a single markdown file:
agent-name.md
├── YAML frontmatter (required)
│ ├── name: (required) - unique identifier
│ ├── description: (required) - trigger conditions
│ ├── model: (optional) - sonnet/opus/haiku/inherit
│ ├── color: (optional) - terminal output color
│ └── tools: (optional) - restrict available tools
└── Markdown body (required)
└── System prompt / instructions
Follow these steps in order when creating an agent.
Gather concrete examples of how the agent will be used:
Key questions to ask:
Example for a code-formatter agent:
Conclude when there's clarity on:
Analyze the use cases to determine:
Follow naming conventions:
Good: code-formatter, pr-reviewer, test-generator
Bad: helper, code-assistant, thing-manager
Write descriptions that ensure proper invocation:
Pattern:
MUST BE USED when user asks to: [action 1], [action 2], [action 3].
[Brief capability description].
| Model | When to Use |
|---|---|
inherit | Default - uses parent model (recommended) |
sonnet | Complex reasoning, multi-step tasks |
haiku | Fast, simple tasks, data extraction |
opus | Most complex tasks requiring deep analysis |
Choose colors based on agent purpose:
Omit the tools field for full access, or restrict to specific tools:
tools: ["Read", "Glob", "Grep"] # Read-only agent
tools: ["Read", "Write", "Edit", "Bash"] # Full file access
Apply least-privilege principle: only include tools the agent needs.
Determine which plugin should contain the agent:
fx-cc Plugin Mapping:
If uncertain, use AskUserQuestion to confirm plugin selection.
Create the agent markdown file in the target plugin:
PLUGIN_PATH=~/.claude/plugins/marketplaces/fx-cc/plugins/<plugin-name>
cat > $PLUGIN_PATH/agents/<agent-name>.md
---
name: agent-name
description: "MUST BE USED when user asks to: [action 1], [action 2]. [Brief description of what the agent does]."
model: inherit
color: blue
tools: ["Tool1", "Tool2"] # Optional - omit for full access
---
Option A: Minimal Agent (~50-100 words) For simple, focused agents:
# Agent Name
## Purpose
[One-liner purpose statement]
## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Key Behaviors
- [Behavior 1]
- [Behavior 2]
Option B: Standard Agent (~200-500 words) For most agents:
# Agent Name
## Purpose
[2-3 sentence description]
## Usage Examples
<example>
Context: [Situation that triggers agent]
user: "[User message]"
assistant: "I'll use the [agent-name] agent to [action]."
<commentary>
[Why agent should trigger]
</commentary>
</example>
## Core Responsibilities
1. [Responsibility 1]
2. [Responsibility 2]
3. [Responsibility 3]
## Workflow
1. **Step 1**: [Description]
2. **Step 2**: [Description]
3. **Step 3**: [Description]
## Quality Standards
- [Standard 1]
- [Standard 2]
## Output Format
[Expected output structure]
Option C: Complex Orchestrator (~500-1000+ words) For agents that coordinate other agents or execute complex workflows:
# Agent Name
## Purpose
[Comprehensive description]
## CRITICAL: MANDATORY STEPS
[Emphasize required workflow]
## Agent/Tool Reference
| Agent | subagent_type | Purpose |
|-------|---------------|---------|
| [Agent 1] | `plugin:agent-1` | [Purpose] |
## MANDATORY WORKFLOW STEPS
### STEP 1: [Phase Name]
[Detailed instructions with code blocks]
### STEP 2: [Phase Name]
[Detailed instructions]
## Error Handling
[How to handle failures]
## Success Criteria
[Checklist of completion criteria]
Include <example> blocks in the description or body:
<example>
Context: User wants to [action] after [situation]
user: "[User message - exact trigger phrase]"
assistant: "I'll use the [agent-name] agent to [what it does]."
<commentary>
[Explain why this triggers the agent and what happens]
</commentary>
</example>
Include 2-4 examples showing:
Validation checklist:
name and description fieldsTesting:
/agents listAfter testing:
See references/agent-patterns.md for detailed examples of: