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:

Type	Official Name	Communication	Use When
A	Subagent	Hierarchical (parent spawns child)	Autonomous task, delegated by an orchestrator
B	Multi-Agent Swarm	Peer-to-peer via sessions (tmux)	Coordinated agents that message each other

Claude Code中的两种不同Agent类型：

类型	官方名称	通信方式	使用场景
A	Subagent	层级式（父Agent生成子Agent）	由编排器委派的自主任务
B	Multi-Agent Swarm	通过会话（tmux）进行对等通信	可相互发送消息的协同Agent

Step 0: Qualify the User's Intent

步骤0：确认用户意图

Before writing any agent, ask these questions:

What task should the agent handle?
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)
Does it need to communicate with other running Claude Code sessions?
- No → Type A: Subagent
- Yes → Type B: Multi-Agent Swarm
Permissions: Should it run commands, edit files, or be read-only?
Should it run in background or block the current session?

在编写任何Agent之前，请询问以下问题：

该Agent应处理什么任务？
它将存储在何处？
- 项目级：
```
.claude/agents/
```
  （与项目所有用户共享）
- 全局级：
```
~/.claude/agents/
```
  （个人使用，适用于所有项目）
- 插件捆绑：
```
skills/my-skill/agents/
```
  （随Skill一起发布）
它是否需要与其他运行中的Claude Code会话通信？
- 不需要 → 类型A：Subagent
- 需要 → 类型B：Multi-Agent Swarm
权限设置：它是否需要运行命令、编辑文件，还是仅为只读权限？
它应在后台运行还是阻塞当前会话？

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配置字段

Field	Required	Values	Notes
`name`	Yes	`lowercase-hyphens`	3–50 chars, start/end alphanumeric
`description`	Yes	Text + `<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`	No	Array of tool names	Omit = all tools
`disallowedTools`	No	Array of tool names	Explicitly deny
`permissionMode`	No	`default` `acceptEdits` `dontAsk` `bypassPermissions` `plan`	Override permission prompts
`maxTurns`	No	Integer	Cap 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`	No	Array of skill paths	Pre-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

状态文件字段

Field	Required	Description
`agent_name`	Yes	Identifier for this agent in the swarm
`task_number`	Yes	Task ordering (e.g. `3.5` )
`coordinator_session`	Yes	tmux session name of the coordinator
`enabled`	Yes	`true` / `false` — agent skips its hook if false
`pr_number`	No	Associated PR number
`dependencies`	No	Task IDs that must complete first
`additional_instructions`	No	Per-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辅助生成工作流

agent-creator

Original

Translation

Agent Creator for Claude Code

适用于Claude Code的Agent创建工具

Overview

概述

Step 0: Qualify the User's Intent

步骤0：确认用户意图

Frontmatter Standard

前置元数据标准

Project Metadata (required on all agents)

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

Agent Configuration Fields

Agent配置字段

Pre-loading Skills (skills field)

预加载Skill（skills字段）

Type A: Subagent

类型A：Subagent

File Template

文件模板

Invocation

调用方式

Natural language — Claude decides

自然语言 — 由Claude决定

@-mention — forces this specific agent for one task

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

Restricting Which Subagents an Orchestrator Can Spawn

限制编排器可生成的Subagent

Description Best Practices

描述最佳实践

System Prompt Design

系统提示词设计

Type B: Multi-Agent Swarm

类型B：Multi-Agent Swarm

When to Use

使用场景

Architecture

架构

State File

状态文件

Task Assignment: Implement Authentication

任务分配：实现认证功能

Requirements

需求

Success Criteria

成功标准

Coordination

协同机制

State File Fields

状态文件字段

Idle Notification Hook

空闲通知钩子

Coordinator System Prompt Pattern

协调器系统提示词模板

Full Swarm Example

完整集群示例

Quick Reference

快速参考

Which type?

如何选择类型？

Minimal Subagent

最简Subagent示例

Reference Files

参考文件

Example Files

示例文件

Pre-loading Skills (
`skills`
field)

预加载Skill（
`skills`
字段）