agent-creator（Agent 创建者）

Agent Creator for Claude Code

Overview

Two distinct agent types in Claude Code:

Step 0: Qualify the User's Intent

Before writing any agent, ask these questions:

1. What task should the agent handle?
2. Where will it live?

- Project: .claude/agents/ (shared with all project users) - Global: ~/.claude/agents/ (personal, all projects) - Plugin-bundled: skills/my-skill/agents/ (ships with a skill)

1. Does it need to communicate with other running Claude Code sessions?

- No → Type A: Subagent - Yes → Type B: Multi-Agent Swarm

1. Permissions: Should it run commands, edit files, or be read-only?
2. Should it run in background or block the current session?

Frontmatter Standard

Every agent file must include project metadata (required by this project) and agent configuration fields.

Project Metadata (required on all agents)

created-at: YYYY-MM-DD
created-by: "Firstname Lastname <email@example.com>"
credits: https://...   # Optional — only if derived from external work

Always ask the user for their first name, last name, and email before writing the file. Never guess or skip created-by.

Agent Configuration Fields

Color guide: blue/cyan = analysis · green = generation · yellow = validation · red = security · magenta = creative/refactoring

Pre-loading Skills (skills field)

When creating an agent, suggest pre-loading relevant skills from the project. Skills give the agent additional domain expertise at startup.

Discover available skills dynamically — before suggesting anything, scan the project:

1. Glob: **/SKILL.md (search both skills/ and .claude/skills/, wherever they live)
2. For each result, read the `name` and `description` fields from the frontmatter
3. Based on the agent's domain, propose the relevant ones

Then ask the user: *"Should this agent have any skills pre-loaded?"* and show only the ones that match the agent's responsibilities.

Example frontmatter with skills:

skills:
  - skills/react-best-practices
  - skills/typescript-advanced-types

Type A: Subagent

A standalone agent spawned hierarchically. An orchestrator (Claude or another agent) delegates a task to it.

File Template

---
created-at: YYYY-MM-DD
created-by: "Firstname Lastname <email@example.com>"

name: my-agent
description: Use this agent when [conditions]. Examples:

<example>
Context: [Situation]
user: "[Request]"
assistant: "[Response using this agent]"
<commentary>
[Why this agent triggers here]
</commentary>
</example>

model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]

**Process:**
1. [Step 1]
2. [Step 2]

**Output Format:**
[What to produce and how to structure it]

Invocation

# Natural language — Claude decides
Use the my-agent subagent to analyze the codebase

# @-mention — forces this specific agent for one task
@"my-agent (agent)" check the auth module

Restricting Which Subagents an Orchestrator Can Spawn

In an orchestrator agent's frontmatter, limit spawnable subagents:

tools: Agent(worker, researcher), Read, Bash

Description Best Practices

The description field is the sole triggering mechanism. Include 2–4 <example> blocks covering:

• Explicit request (user directly asks)
• Proactive triggering (agent activates after relevant work)
• Variations in phrasing

See references/triggering-examples.md for the full guide.

System Prompt Design

Write in second person (You are..., You will...). See references/system-prompt-design.md for complete patterns (Analysis, Generation, Validation, Orchestration) with structure templates and edge case guidance.

Type B: Multi-Agent Swarm

Multiple Claude Code sessions coordinating via shared state. Each session runs independently and notifies a coordinator when idle.

When to Use

• Tasks that can be parallelized (multiple PRs, multiple services, multiple modules)
• Workflows requiring specialized agents for different phases
• Long-running work exceeding a single session's context
• Independent tasks with explicit dependencies

Architecture

Coordinator session (e.g. "team-leader")
    ├── Worker session A ("auth-agent")    → works on Task 3.5
    ├── Worker session B ("db-agent")      → works on Task 4.2
    └── Worker session C ("api-agent")     → works on Task 5.1
         ↕ communicate via tmux send-keys

State File

Each worker session reads .claude/multi-agent-swarm.local.md to know its task and coordinator:

---
agent_name: auth-agent
task_number: 3.5
pr_number: TBD
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: "Use JWT, not sessions"
---

# Task Assignment: Implement Authentication

## Requirements
- JWT token generation and validation
- Refresh token flow

## Success Criteria
- Auth endpoints pass all tests
- PR created and CI green

## Coordination
Depends on Task 3.4 (user model).
Report status to coordinator session 'team-leader'.

State File Fields

Idle Notification Hook

Add a Stop hook to each worker's .claude/settings.json that calls a notify script on idle. See examples/complete-agent-examples.md → Example 5 for the full settings.json block and notify-coordinator.sh script.

Coordinator System Prompt Pattern

You are the coordinator of a multi-agent swarm managing parallel development tasks.

**Your Core Responsibilities:**
1. Assign tasks to worker agents via their tmux sessions
2. Track task dependencies — only assign a task when its dependencies are complete
3. Handle worker notifications (agents message you when idle)
4. Consolidate completed work into a final report

**Coordination Process:**
1. Maintain a backlog of pending tasks with their dependencies
2. When a worker becomes idle: identify the next unblocked task and assign it
3. To assign a task: tmux send-keys -t <session> "<task description>" Enter
4. When all tasks complete: produce a summary of all PRs and outcomes

**State:** Track which tasks are pending/in-progress/done, and which session owns each.

Full Swarm Example

See examples/complete-agent-examples.md → "Example 5: Multi-Agent Swarm".

Quick Reference

Which type?

Does the agent need to message other running Claude Code sessions?
├── No  → Type A: Subagent
│         .claude/agents/my-agent.md
└── Yes → Type B: Multi-Agent Swarm
          .claude/multi-agent-swarm.local.md

Minimal Subagent

---
created-at: 2026-03-31
created-by: "Name <email>"
name: my-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
---
You are an agent that does X.
1. Step one
2. Step two
Output: [what to produce]

Reference Files

• references/system-prompt-design.md — Patterns for Analysis, Generation, Validation, Orchestration agents
• references/triggering-examples.md — Writing <example> blocks for reliable triggering
• references/agent-creation-system-prompt.md — AI-assisted agent generation prompt

Example Files

• examples/complete-agent-examples.md — Production-ready templates (subagents + swarm)
• examples/agent-creation-prompt.md — AI-assisted generation workflow