create-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Creator

Agent 创建器

Generate well-structured Claude Code agents — markdown files with YAML frontmatter that delegate complex multi-step work to autonomous subprocesses with isolated context windows.

Agents vs Skills — know the difference before generating:

Agents run in isolated context, have second-person system prompts ("You are..."), use concise
```
>
```
folded scalar descriptions (50-70 tokens, no
```
<example>
```
blocks), and are spawned via the Agent tool
Skills inject inline into the current conversation, use imperative body instructions for Claude to follow, and route via description matching on trigger phrases

生成结构规范的Claude Code Agent——带有YAML前置元数据的Markdown文件，可将复杂的多步骤任务委托给具有独立上下文窗口的自主子进程处理。

Agent 与 Skill 的区别——生成前请明确：

Agent 在独立上下文环境中运行，采用第二人称系统提示词（"You are..."），使用简洁的
```
>
```
折叠标量描述（50-70个token，无
```
<example>
```
块），通过Agent工具启动
Skill 直接注入当前对话流程，使用祈使句格式为Claude提供执行指令，通过触发短语的描述匹配进行路由

Phase 0: Understand Requirements

阶段0：需求理解

Parse

$ARGUMENTS

for hints. Gather:

Identity:

Domain & purpose — What problem does this agent solve?
Expert persona — What specialist identity should it embody?

Triggering: 3. Trigger conditions — When should Claude delegate to this agent? What user messages activate it? 4. Proactive vs reactive — Should it fire automatically after events (e.g., after code is written), or only on explicit request?

Capabilities: 5. Tool access — What tools are actually needed? Least-privilege: an analysis agent doesn't need Write. 6. Memory — Should this agent learn across sessions? (e.g., accumulate codebase patterns, recurring issues, architectural decisions.) If yes, choose scope:

project

(recommended default, shareable via VCS),

user

(global across projects), or

local

(project-specific, not in VCS). 7. MCP servers — Does it need external tools (browser, database, API) not in the parent session?

Execution: 8. Session mode — Will this run as a subagent (delegated by Claude) or as the main session agent (

claude --agent <name>

)? Session agents need broader tool access, more self-contained prompts, and may use

initialPrompt

to self-start. 9. Background execution — Should it run concurrently while the user continues? Background agents auto-deny unpre-approved permissions and cannot ask clarifying questions. 10. Context isolation — Does it generate heavy output or modify files? Should it run in a worktree (

isolation: worktree

)? 11. Effort level — Does it need deep reasoning (

high

max

) or is it a fast classification task (

low

$ARGUMENTS

is empty or insufficient, use AskUserQuestion to gather domain, trigger conditions, and proactive intent before proceeding. Proceed to Phase 1 once these are established.

解析

$ARGUMENTS

获取提示信息，收集以下内容：

身份定位：

领域与用途——该Agent要解决什么问题？
专家角色——它应具备何种专业身份？

触发机制： 3. 触发条件——Claude应在何时委托给该Agent？哪些用户消息会激活它？ 4. 主动触发 vs 被动响应——它是否应在特定事件后自动触发（例如代码编写完成后），还是仅在用户明确请求时激活？

能力配置： 5. 工具权限——实际需要哪些工具？遵循最小权限原则：分析类Agent无需Write权限。 6. 记忆功能——该Agent是否需要跨会话学习？（例如积累代码库模式、常见问题、架构决策。）若需要，选择记忆范围：

project

（推荐默认值，可通过版本控制系统共享）、

user

（跨项目全局共享）或

local

（项目专属，不纳入版本控制系统）。 7. MCP服务器——它是否需要父会话中未包含的外部工具（浏览器、数据库、API）？

执行配置： 8. 会话模式——它将作为子Agent（由Claude委托）运行，还是作为主会话Agent（

claude --agent <name>

）？主会话Agent需要更广泛的工具权限、更独立的提示词，可能需使用

initialPrompt

实现自启动。 9. 后台执行——是否允许它在用户继续操作时并发运行？后台Agent会自动拒绝未预先批准的权限，且无法提出澄清问题。 10. 上下文隔离——它是否会生成大量输出或修改文件？是否需要在工作树中运行（

isolation: worktree

）？ 11. 算力级别——它是否需要深度推理（

high

max

），还是仅需快速分类任务（

low

）？

若

$ARGUMENTS

为空或信息不足，使用AskUserQuestion工具收集领域、触发条件和主动触发意图后再继续。当上述信息明确后，进入阶段1。

Phase 1: Generate

阶段1：生成Agent

Apply throughout: second-person for system prompt body, intensional over extensional reasoning, minimum viable frontmatter.

全程遵循以下规则：系统提示词使用第二人称，采用内涵式而非外延式推理，仅保留必要的前置元数据。

Step 1 — Choose identifier

步骤1：选择标识符

Naming rules (enforced by

validate_agent.py

3–50 characters, lowercase letters/numbers/hyphens only
Must start and end with alphanumeric
Avoid generic terms:
```
helper
```
,
```
assistant
```
,
```
agent
```

Good:

code-reviewer

test-generator

api-docs-writer

Bad:

ag

(too short),

-start

(leading hyphen),

my_agent

(underscore)

命名规则（由

validate_agent.py

强制执行）：

3–50个字符，仅允许小写字母/数字/连字符
必须以字母或数字开头和结尾
避免通用术语：
```
helper
```
、
```
assistant
```
、
```
agent
```

示例：

规范命名：

code-reviewer

、

test-generator

、

api-docs-writer

不规范命名：
```
ag
```
（过短）、
```
-start
```
（以连字符开头）、
```
my_agent
```
（使用下划线）

Step 2 — Write frontmatter

步骤2：编写前置元数据

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md

for the full field catalog, color semantics, model options, tool selection framework, and execution modifiers.

Required:

name

description

Always set:

model: inherit

(unless specific model capability needed),

color

(visual ID in UI)

Intensional rule for
tools
: Restrict to the minimum needed because agents run autonomously — over-permission has no human in the loop to catch it.

["Read", "Grep", "Glob"]

for analysis. Add

Write

for generation. Add

Bash

only when shell execution is essential, never by default. For session-mode agents that orchestrate subagents, use

Agent(type1, type2)

to scope spawning.

Set if applicable from Phase 0:

```
memory
```
— if cross-session learning was identified; add memory maintenance instructions to body
```
effort
```
— if the task warrants non-default thinking depth
```
initialPrompt
```
— if this is a session agent that should self-start
```
background: true
```
— if concurrent execution was identified
```
mcpServers
```
— if external tools were identified

阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md

获取完整字段目录、颜色语义、模型选项、工具选择框架和执行修饰符。

必填字段：

name

、

description

必须设置：

model: inherit

（除非需要特定模型能力）、

color

（UI中的视觉标识）

tools

字段的内涵式规则：**仅保留必要的最小权限，因为Agent是自主运行的——过度授权会导致无人监管的风险。分析类Agent使用

["Read", "Grep", "Glob"]

；生成类Agent添加

Write

权限；仅当必须执行shell命令时才添加

Bash

权限，默认不添加。对于需要编排子Agent的会话模式Agent，使用

Agent(type1, type2)

限定可启动的Agent类型。

根据阶段0的需求设置以下字段（如适用）：

```
memory
```
——若确定需要跨会话学习；在提示词正文中添加记忆维护说明
```
effort
```
——若任务需要非默认的思考深度
```
initialPrompt
```
——若为需要自启动的会话模式Agent
```
background: true
```
——若确定需要并发执行
```
mcpServers
```
——若确定需要外部工具

Step 3 — Write description

步骤3：编写描述

The description field is loaded into context every session. Token budget matters — write the minimum needed for accurate routing.

Use a

folded scalar with:

"Use this agent when [trigger conditions]."
Proactive hint if applicable ("Recommended PROACTIVELY after...")
Scope boundary ("Not for X — use Y-agent.")
Target: 50-70 tokens. No
```
<example>
```
blocks — they waste context without improving routing.

描述字段会在每个会话中加载到上下文，需注意token预算——仅编写准确路由所需的最少内容。

使用

折叠标量格式，包含：

"Use this agent when [触发条件]."
主动触发提示（如适用："Recommended PROACTIVELY after..."）
范围边界说明（"Not for X — use Y-agent."）
目标长度：50-70个token。请勿使用
```
<example>
```
块——它们会浪费上下文且无法提升路由准确性。

Step 4 — Write system prompt

步骤4：编写系统提示词

The markdown body (after

---

) becomes the agent's system prompt. Write entirely in second person, addressing the agent directly. This is the critical authoring difference from skills: agents need a persona and process, not instructions for Claude to follow.

Standard structure:

markdown

You are [role] specializing in [domain].

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

**Process:**
1. [Step — imperative]
2. [Next step]

**Quality Standards:**
- [Standard]

**Output Format:**
[Structure and content of what to return]

**Edge Cases:**
- [Situation]: [How to handle]

Intensional rules for the system prompt:

Persona first — the expert identity shapes all downstream decisions; establish it in the first sentence
Process steps prevent "winging it" on complex tasks; each step is an explicit decision boundary
Output format is non-negotiable — callers need predictable structure to consume results
Define edge cases in the system prompt; discovered-at-runtime errors cost retries

If
memory
is set: Include a section instructing the agent to maintain its knowledge base: "Update your agent memory as you discover codepaths, patterns, and key architectural decisions. Consult your memory before starting work." This enables cross-session learning.

Keep under 3,000 words. Detailed domain reference belongs in

references/

preloaded via the

skills:

frontmatter field, not embedded directly in the system prompt.

See

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md

for a complete working example demonstrating the proactive trigger pattern.

Markdown正文（

---

之后的内容）将成为Agent的系统提示词。全程使用第二人称，直接对Agent进行表述。这是与Skill的关键区别：Agent需要明确的角色和流程，而非给Claude的执行指令。

标准结构：

markdown

You are [角色] specializing in [领域].

**Your Core Responsibilities:**
1. [主要职责]
2. [次要职责]

**Process:**
1. [步骤——祈使句]
2. [下一步]

**Quality Standards:**
- [标准]

**Output Format:**
[返回结果的结构和内容]

**Edge Cases:**
- [场景]: [处理方式]

系统提示词的内涵式规则：

先明确角色——专家身份会影响后续所有决策；在第一句就确立角色
流程步骤可避免复杂任务中的随意性；每个步骤都是明确的决策边界
输出格式必须明确——调用方需要可预测的结构来处理结果
在系统提示词中定义边缘情况；运行时发现的错误会导致重试成本

**若设置了

memory

：**添加一个章节指导Agent维护其知识库："Update your agent memory as you discover codepaths, patterns, and key architectural decisions. Consult your memory before starting work." 这将实现跨会话学习。

保持在3000字以内。详细的领域参考内容应放在

references/

目录中，通过

skills:

前置元数据字段预加载，而非直接嵌入系统提示词。

参考

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md

获取完整的工作示例，展示主动触发模式。

Step 5 — Script opportunity scan

步骤5：脚本化机会扫描

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md

and apply the five signal patterns to every step in the agent's system prompt:

Signal	Question	If yes →
Repeated Generation	Does any step produce the same structure across invocations?	Parameterized script in `scripts/`
Unclear Tool Choice	Does any step combine tools in a fragile sequence?	Script the procedure
Rigid Contract	Can you write `--help` text for this step right now?	CLI candidate
Dual-Use Potential	Would a user run this step from the terminal independently?	Design as proper CLI
Consistency Critical	Must this step produce identical output for identical inputs?	Script — never LLM generation

阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md

，并将五种信号模式应用于Agent系统提示词的每个步骤：

信号	问题	如果是 →
重复生成	是否有步骤在每次调用时生成相同结构的内容？	在 `scripts/` 目录中创建参数化脚本
工具选择模糊	是否有步骤以脆弱的方式组合多个工具？	将流程脚本化
严格契约	你现在能否为该步骤编写 `--help` 文本？	可作为CLI候选
双重用途潜力	用户是否会独立从终端运行该步骤？	设计为正式CLI工具
一致性要求高	该步骤是否必须为相同输入生成相同输出？	脚本化——绝不使用LLM生成

Step 6 — Check delegation

步骤6：检查委托关系

Scan existing agents and skills before finalizing:

Glob: .claude/agents/*.md, ~/.claude/agents/*.md (project + global agents)
Glob: .claude/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md (project + global skills)

Does an existing agent cover this domain? Extend it, or tighten scope of the new one
Are there skills or reference files to preload via
```
skills:
```
frontmatter for domain knowledge?
Are there commands or MCPs this agent should delegate sub-tasks to?

Always use fully qualified names:

Agent: subagent_type=plugin-dev:agent-creator

(not just "agent-creator")

```
Skill: claude-skills:create-skill
```
(not just "create-skill")

在最终确定前，扫描现有Agent和Skill：

Glob: .claude/agents/*.md, ~/.claude/agents/*.md (项目 + 全局Agent)
Glob: .claude/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md (项目 + 全局Skill)

是否已有Agent覆盖该领域？扩展现有Agent，或缩小新Agent的范围
是否有可通过
```
skills:
```
前置元数据字段预加载的Skill或参考文件，以提供领域知识？
是否有该Agent可委托子任务的命令或MCP？

始终使用完整限定名称：

Agent: subagent_type=plugin-dev:agent-creator

（不要仅写"agent-creator"）

```
Skill: claude-skills:create-skill
```
（不要仅写"create-skill"）

Step 7 — Validate

步骤7：验证

When creating a new agent file:

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py <agent-file> --output json

Exit 0 = proceed to Phase 2. Exit 1 = parse the

errors

array; each entry has

field

message

severity

. Resolve all

critical

and

major

items before writing to disk.

创建新Agent文件时：

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py <agent-file> --output json

返回码0 = 进入阶段2。返回码1 = 解析

errors

数组；每个条目包含

field

、

message

、

severity

。在写入磁盘前解决所有

critical

和

major

级别的问题。

Phase 2: Deliver

阶段2：交付

Output Paths

输出路径

Scope	Location
User agent (global)	`~/.claude/agents/<name>.md`
Project agent	`.claude/agents/<name>.md`
Plugin agent	`<plugin-root>/agents/<name>.md`

Agents in

agents/

are auto-discovered — no registration needed. Plugin agents are namespaced automatically as

plugin-name:agent-name

范围	位置
用户全局Agent	`~/.claude/agents/<name>.md`
项目Agent	`.claude/agents/<name>.md`
插件Agent	`<plugin-root>/agents/<name>.md`

agents/

目录下的Agent会被自动发现——无需注册。插件Agent会自动命名为

plugin-name:agent-name

格式。

Initialize agent file (optional scaffold)

初始化Agent文件（可选脚手架）

When creating from scratch:

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/init_agent.py <name> --path <agents-dir>

Exit 0 = file created with placeholders, proceed to fill content. Exit 1 = naming collision; ask user to rename or confirm overwrite.

从零创建时：

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/init_agent.py <name> --path <agents-dir>

返回码0 = 文件已创建并包含占位符，可继续填充内容。返回码1 = 命名冲突；询问用户重命名或确认覆盖。

Explain Your Choices

解释决策依据

Present the generated agent with brief rationale:

What you set and why — "Set
```
model: sonnet
```
because this agent performs complex multi-file reasoning"
What you excluded and why — "Left
```
isolation
```
unset; no git state management needed"
Tools selected and why — explicitly justify each tool; undefended tool access is a design smell

展示生成的Agent并提供简要说明：

设置内容及原因——"设置
```
model: sonnet
```
是因为该Agent需要处理复杂的多文件推理"
未设置内容及原因——"未设置
```
isolation
```
；无需Git状态管理"
所选工具及原因——明确说明每个工具的必要性；无依据的工具权限是设计缺陷

Write and Confirm

写入并确认

Before writing:

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

写入前：

将写入至：[路径]
这将[创建新文件 / 覆盖现有文件]。
是否继续？

After Creation

创建完成后

Summarize:

Name and file path
When it triggers (key trigger conditions)
Tools granted and why
Suggested test scenario

Proceed to Phase 3.

总结内容：

名称和文件路径
触发时机（关键触发条件）
授予的工具及原因
建议的测试场景

进入阶段3。

Phase 3: Evaluate

阶段3：评估

Dimension	Criteria
Clarity (0-10)	System prompt unambiguous, objective and persona clear
Trigger Precision (0-10)	Description + examples cover intended trigger space, not broader
Efficiency (0-10)	System prompt token economy — maximum guidance per token
Completeness (0-10)	Covers domain requirements; output format defined; edge cases addressed
Safety (0-10)	Tools restricted to minimum needed; no runaway permission grants

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Phase 3 is complete when score ≥ 9.0 or one refinement pass has run. Deliver: agent file path, key trigger conditions, tools granted and why.

维度	评估标准
清晰度（0-10）	系统提示词明确无歧义，目标和角色清晰
触发精度（0-10）	描述+示例覆盖预期触发场景，无过度宽泛
效率（0-10）	系统提示词token经济性——每个token提供最大指导价值
完整性（0-10）	覆盖领域需求；定义输出格式；处理边缘情况
安全性（0-10）	工具权限限制在最小必要范围；无过度授权

目标：9.0/10.0。 若低于该分数，针对最弱维度进行一次优化后再交付。

当分数≥9.0或完成一次优化后，阶段3结束。交付内容：Agent文件路径、关键触发条件、授予的工具及原因。

Validation Checklist

验证 checklist

Structure:

File is
```
<name>.md
```
in an
```
agents/
```
directory
Valid YAML frontmatter with
```
name
```
and
```
description
```
Markdown body is present and substantial

Description Quality:

Starts with "Use this agent when..."
Concise
```
>
```
scalar, 50-70 tokens, no
```
<example>
```
blocks
Covers scope boundaries (what it's NOT for)
Proactive hint included if agent should fire after events

System Prompt Quality:

Written in second person ("You are...", "You will...")
Has clear persona/role statement as first sentence
Process steps are numbered and imperative
Output format is defined
Edge cases addressed
Under 3,000 words; domain detail offloaded to references/

Frontmatter:

```
model: inherit
```
unless specific model needed
```
color
```
set and semantically meaningful
```
tools
```
restricted to minimum needed
```
memory
```
set if cross-session learning identified, with maintenance instructions in body
```
effort
```
set if non-default thinking depth needed
```
initialPrompt
```
set if session-mode agent that self-starts
```
background: true
```
set if concurrent execution identified
```
isolation: worktree
```
set if agent modifies files that need review before merging
No TODO placeholders remaining

结构：

文件为
```
<name>.md
```
格式，位于
```
agents/
```
目录下
包含有效的YAML前置元数据，且包含
```
name
```
和
```
description
```
字段
存在实质性的Markdown正文

描述质量：

以"Use this agent when..."开头
使用简洁的
```
>
```
标量，长度50-70个token，无
```
<example>
```
块
包含范围边界说明（明确不适用场景）
若Agent需在事件后自动触发，包含主动触发提示

系统提示词质量：

使用第二人称（"You are...", "You will..."）
第一句为清晰的角色/身份声明
流程步骤采用编号和祈使句格式
定义了输出格式
处理了边缘情况
字数在3000以内；领域细节转移至references/目录

前置元数据：

```
model: inherit
```
（除非需要特定模型）
设置了
```
color
```
且具有语义意义
```
tools
```
限制在最小必要范围
若确定需要跨会话学习，设置了
```
memory
```
并在正文中添加维护说明
若需要非默认思考深度，设置了
```
effort
```
若为自启动的会话模式Agent，设置了
```
initialPrompt
```
若需要并发执行，设置了
```
background: true
```
若Agent修改的文件需要在合并前审核，设置了
```
isolation: worktree
```
无剩余的TODO占位符

Error Handling

错误处理

Issue	Action
Unclear domain	Ask: what does success look like for this agent?
Scope too broad	Split into 2–3 focused agents with non-overlapping trigger conditions
Conflicts with existing agent	Note overlap; narrow triggering scope or extend the existing one
Vague trigger conditions	Ask for 3 concrete user messages that should activate this agent

问题	操作
领域不明确	询问：该Agent成功的标准是什么？
范围过于宽泛	拆分为2–3个聚焦的Agent，确保触发条件无重叠
与现有Agent冲突	标注重叠部分；缩小触发范围或扩展现有Agent
触发条件模糊	询问用户提供3个应激活该Agent的具体用户消息示例