Back to Details

agent-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Creator for Claude Code

适用于Claude Code的Agent创建工具

Overview

概述

Two distinct agent types in Claude Code:
TypeOfficial NameCommunicationUse When
ASubagentHierarchical (parent spawns child)Autonomous task, delegated by an orchestrator
BMulti-Agent SwarmPeer-to-peer via sessions (tmux)Coordinated agents that message each other
Claude Code中的两种不同Agent类型：
类型官方名称通信方式使用场景
ASubagent层级式（父Agent生成子Agent）由编排器委派的自主任务
BMulti-Agent Swarm通过会话（tmux）进行对等通信可相互发送消息的协同Agent

Step 0: Qualify the User's Intent

步骤0：确认用户意图

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)
  3. Does it need to communicate with other running Claude Code sessions?
    • No → Type A: Subagent
    • Yes → Type B: Multi-Agent Swarm
  4. Permissions: Should it run commands, edit files, or be read-only?
  5. Should it run in background or block the current session?
在编写任何Agent之前，请询问以下问题：
  1. 该Agent应处理什么任务？
  2. 它将存储在何处？
    • 项目级：
      .claude/agents/
      （与项目所有用户共享）
    • 全局级：
      ~/.claude/agents/
      （个人使用，适用于所有项目）
    • 插件捆绑：
      skills/my-skill/agents/
      （随Skill一起发布）
  3. 它是否需要与其他运行中的Claude Code会话通信？
    • 不需要 → 类型A：Subagent
    • 需要 → 类型B：Multi-Agent Swarm
  4. 权限设置：它是否需要运行命令、编辑文件，还是仅为只读权限？
  5. 它应在后台运行还是阻塞当前会话？

Frontmatter Standard

前置元数据标准

Every agent file must include project metadata (required by this project) and agent configuration fields.
每个Agent文件必须包含项目元数据（本项目要求必填）和Agent配置字段。

Project Metadata (required on all agents)

项目元数据（所有Agent必填）

yaml
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
.
yaml
created-at: YYYY-MM-DD
created-by: "Firstname Lastname <email@example.com>"
credits: https://...   # 可选 — 仅当基于外部工作衍生时填写
在编写文件前，务必向用户询问其姓名和邮箱。切勿猜测或跳过
created-by
字段。

Agent Configuration Fields

Agent配置字段

FieldRequiredValuesNotes
name
Yes
lowercase-hyphens
3–50 chars, start/end alphanumeric
description
YesText + 
<example>
blocks		Primary triggering mechanism
model
No
inherit
, 
sonnet
, 
opus
, 
haiku
, full model ID		Default: 
inherit
color
No
blue
cyan
green
yellow
magenta
red
UI identifier
tools
NoArray of tool namesOmit = all tools
disallowedTools
NoArray of tool namesExplicitly deny
permissionMode
No
default
acceptEdits
dontAsk
bypassPermissions
plan
Override permission prompts
maxTurns
NoIntegerCap agentic turns
background
No
true
/
false
Run without blocking current session
effort
No
low
medium
high
max
Reasoning effort level
isolation
No
worktree
Isolated git worktree environment
memory
No
user
project
local
Persistent memory scope
skills
NoArray of skill pathsPre-loaded skills at startup
Color guide: blue/cyan = analysis · green = generation · yellow = validation · red = security · magenta = creative/refactoring
字段是否必填可选值说明
name
是
小写连字符格式
3–50个字符，首尾为字母数字
description
是文本 + 
<example>
块		主要触发机制
model
否
inherit
, 
sonnet
, 
opus
, 
haiku
, 完整模型ID		默认值：
inherit
color
否
blue
cyan
green
yellow
magenta
red
UI识别标识
tools
否工具名称数组省略则启用所有工具
disallowedTools
否工具名称数组明确禁用指定工具
permissionMode
否
default
acceptEdits
dontAsk
bypassPermissions
plan
覆盖权限提示设置
maxTurns
否整数限制Agent交互轮次
background
否
true
/
false
在不阻塞当前会话的情况下运行
effort
否
low
medium
high
max
推理努力级别
isolation
否
worktree
隔离的git工作树环境
memory
否
user
project
local
持久化内存范围
skills
否Skill路径数组启动时预加载的Skill
颜色指南： blue/cyan = 分析 · green = 生成 · yellow = 验证 · red = 安全 · magenta = 创意/重构

Pre-loading Skills (
skills
field)

预加载Skill（
skills
字段）

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:
yaml
skills:
  - skills/react-best-practices
  - skills/typescript-advanced-types
创建Agent时，建议从项目中预加载相关Skill。Skill可为Agent在启动时提供额外的领域专业知识。
动态发现可用Skill — 在提出建议前，先扫描项目：
1. 全局搜索：**/SKILL.md（搜索skills/和.claude/skills/目录，无论其位置）
2. 对于每个结果，从前置元数据中读取`name`和`description`字段
3. 根据Agent的领域，推荐相关的Skill
然后询问用户：“是否需要为该Agent预加载某些Skill？” 并仅展示与Agent职责匹配的Skill。
包含Skill的前置元数据示例：
yaml
skills:
  - skills/react-best-practices
  - skills/typescript-advanced-types

Type A: Subagent

类型A：Subagent

A standalone agent spawned hierarchically. An orchestrator (Claude or another agent) delegates a task to it.
独立的层级式生成Agent。编排器（Claude或其他Agent）将任务委派给它。

File Template

文件模板

markdown
---
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]
markdown
---
created-at: YYYY-MM-DD
created-by: "Firstname Lastname <email@example.com>"

name: my-agent
description: 在[条件]下使用此Agent。示例：

<example>
上下文：[场景]
用户："[请求]"
助手："[使用此Agent的响应]"
<commentary>
[此Agent在此处触发的原因]
</commentary>
</example>

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

你是专注于[领域]的[角色]。

**核心职责：**
1. [主要职责]
2. [次要职责]

**流程：**
1. [步骤1]
2. [步骤2]

**输出格式：**
[需生成的内容及其结构]

Invocation

调用方式

undefined
undefined

Natural language — Claude decides

自然语言 — 由Claude决定

Use the my-agent subagent to analyze the codebase
使用my-agent子Agent分析代码库

@-mention — forces this specific agent for one task

@提及 — 强制指定此Agent执行单个任务

@"my-agent (agent)" check the auth module
undefined
@"my-agent (agent)" 检查认证模块
undefined

Restricting Which Subagents an Orchestrator Can Spawn

限制编排器可生成的Subagent

In an orchestrator agent's frontmatter, limit spawnable subagents:
yaml
tools: Agent(worker, researcher), Read, Bash
在编排器Agent的前置元数据中，限制可生成的Subagent：
yaml
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.
description
字段是唯一的触发机制。包含2–4个
<example>
块，涵盖：
  • 明确请求（用户直接询问）
  • 主动触发（Agent在相关工作后激活）
  • 表述变体
完整指南请参阅
references/triggering-examples.md
。

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.
使用第二人称撰写（
你是...
，
你将...
）。完整模式（分析、生成、验证、编排）及结构模板和边缘情况指导，请参阅
references/system-prompt-design.md
。

Type B: Multi-Agent Swarm

类型B：Multi-Agent Swarm

Multiple Claude Code sessions coordinating via shared state. Each session runs independently and notifies a coordinator when idle.
多个Claude Code会话通过共享状态进行协同。每个会话独立运行，并在空闲时通知协调器。

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
  • 可并行化的任务（多个PR、多个服务、多个模块）
  • 不同阶段需要专业Agent的工作流
  • 超出单个会话上下文限制的长时间运行任务
  • 具有明确依赖关系的独立任务

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
协调器会话（例如"team-leader"）
    ├── 工作者会话A（"auth-agent"）    → 处理任务3.5
    ├── 工作者会话B（"db-agent"）      → 处理任务4.2
    └── 工作者会话C（"api-agent"）     → 处理任务5.1
         ↕ 通过tmux send-keys进行通信

State File

状态文件

Each worker session reads 
.claude/multi-agent-swarm.local.md
to know its task and coordinator:
yaml
---
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"
---
每个工作者会话读取
.claude/multi-agent-swarm.local.md
以了解其任务和协调器：
yaml
---
agent_name: auth-agent
task_number: 3.5
pr_number: TBD
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: "使用JWT，而非会话"
---

Task Assignment: Implement Authentication

任务分配：实现认证功能

Requirements

需求

  • JWT token generation and validation
  • Refresh token flow
  • JWT令牌生成与验证
  • 刷新令牌流程

Success Criteria

成功标准

  • Auth endpoints pass all tests
  • PR created and CI green
  • 认证端点通过所有测试
  • 创建PR且CI验证通过

Coordination

协同机制

Depends on Task 3.4 (user model). Report status to coordinator session 'team-leader'.
undefined
依赖于任务3.4（用户模型）。 向协调器会话'team-leader'报告状态。
undefined

State File Fields

状态文件字段

FieldRequiredDescription
agent_name
YesIdentifier for this agent in the swarm
task_number
YesTask ordering (e.g. 
3.5
)
coordinator_session
Yestmux session name of the coordinator
enabled
Yes
true
/
false
— agent skips its hook if false
pr_number
NoAssociated PR number
dependencies
NoTask IDs that must complete first
additional_instructions
NoPer-agent override instructions
字段是否必填描述
agent_name
是集群中此Agent的标识符
task_number
是任务顺序（例如
3.5
）
coordinator_session
是协调器的tmux会话名称
enabled
是
true
/
false
— 若为false，Agent将跳过其钩子
pr_number
否关联的PR编号
dependencies
否必须先完成的任务ID
additional_instructions
否针对该Agent的覆盖指令

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.
在每个工作者的
.claude/settings.json
中添加
Stop
钩子，使其在空闲时调用通知脚本。完整的
settings.json
块和
notify-coordinator.sh
脚本，请参阅
examples/complete-agent-examples.md
→ 示例5。

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.
你是管理并行开发任务的多Agent集群协调器。

**核心职责：**
1. 通过tmux会话向工作者Agent分配任务
2. 跟踪任务依赖关系 — 仅在依赖任务完成后分配新任务
3. 处理工作者通知（Agent在空闲时向你发送消息）
4. 将已完成的工作整合为最终报告

**协同流程：**
1. 维护带有依赖关系的待处理任务积压
2. 当工作者空闲时：识别下一个未阻塞的任务并分配
3. 分配任务：tmux send-keys -t <session> "<任务描述>" Enter
4. 所有任务完成后：生成所有PR和结果的摘要

**状态跟踪：** 记录哪些任务处于待处理/进行中/已完成状态，以及每个任务所属的会话。

Full Swarm Example

完整集群示例

See 
examples/complete-agent-examples.md
→ "Example 5: Multi-Agent Swarm".
请参阅
examples/complete-agent-examples.md
→ “示例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
该Agent是否需要与其他运行中的Claude Code会话通信？
├── 不需要  → 类型A：Subagent
│         .claude/agents/my-agent.md
└── 需要 → 类型B：Multi-Agent Swarm
          .claude/multi-agent-swarm.local.md

Minimal Subagent

最简Subagent示例

yaml
---
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]
yaml
---
created-at: 2026-03-31
created-by: "Name <email>"
name: my-agent
description: 在...场景下使用此Agent。示例：<example>...</example>
model: inherit
---
你是一个执行X任务的Agent。
1. 步骤一
2. 步骤二
输出：[需生成的内容]

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
  • references/system-prompt-design.md
    — 分析、生成、验证、编排型Agent的模板
  • references/triggering-examples.md
    — 编写
    <example>
    块以实现可靠触发的指南
  • references/agent-creation-system-prompt.md
    — AI辅助Agent生成提示词

Example Files

示例文件

  • examples/complete-agent-examples.md
    — Production-ready templates (subagents + swarm)
  • examples/agent-creation-prompt.md
    — AI-assisted generation workflow
  • examples/complete-agent-examples.md
    — 生产就绪模板（Subagent + 集群）
  • examples/agent-creation-prompt.md
    — AI辅助生成工作流