create-agent

Agent Creator

生成结构良好的 Claude Code Agent——带有 YAML frontmatter 的 Markdown 文件，可将复杂的多步骤工作委派给拥有独立上下文窗口的自主子进程。

Agents 与 Skills 的区别——生成前请先了解：

• Agents 在隔离上下文中运行，采用第二人称系统提示词（“You are...”），使用简洁的 > 折叠标量描述（50–70 个 token，不含 <example> 块），并通过 Agent 工具启动
• Skills 会注入当前对话，使用祈使式正文指令供 Claude 遵循，并根据触发短语匹配描述进行路由

阶段 0：了解需求

解析 $ARGUMENTS，寻找线索。收集以下信息：

身份：

1. 领域与目的 — 这个 Agent 要解决什么问题？
2. 专家角色 — 它应具备怎样的专业身份？

触发方式： 3. 触发条件 — Claude 应在何时将任务委派给这个 Agent？哪些用户消息会激活它？ 4. 主动触发还是被动响应 — 它应在事件发生后自动触发（例如，代码编写完成后），还是仅在用户明确请求时触发？

能力： 5. 工具访问权限 — 实际需要哪些工具？遵循最小权限原则：分析 Agent 不需要 Write。 6. 记忆 — 这个 Agent 是否应在不同会话间持续学习？（例如，积累代码库模式、常见问题、架构决策。）如果需要，选择范围：project（推荐默认值，可通过 VCS 共享）、user（适用于所有项目）或 local（仅限当前项目，不纳入 VCS）。 7. MCP 服务 — 它是否需要父会话中没有的外部工具（浏览器、数据库、API）？

执行： 8. 会话模式 — 它会作为子 Agent 运行（由 Claude 委派），还是作为主会话 Agent 运行（claude --agent <name>）？会话 Agent 需要更广泛的工具访问权限、更完善且自成一体的提示词，并且可以使用 initialPrompt 自行启动。 9. 后台执行 — 用户继续操作时，它是否应并发运行？后台 Agent 会自动拒绝未预先批准的权限请求，也无法提出澄清问题。 10. 上下文隔离 — 它会生成大量输出或修改文件吗？是否应在工作树中运行（isolation: worktree）？ 11. 工作量级别 — 是否需要深入推理（high/max），还是只需快速分类（low）？

如果 $ARGUMENTS 为空或信息不足，请使用 AskUserQuestion 询问领域、触发条件和主动触发意图。明确这些信息后，进入阶段 1。

阶段 1：生成

贯穿整个过程：系统提示词正文采用第二人称，优先使用内涵式而非外延式推理，并采用满足需求的最精简 frontmatter。

步骤 1 — 选择标识符

命名规则（由 validate_agent.py 强制执行）：

• 长度为 3–50 个字符，只能包含小写字母、数字和连字符
• 必须以字母或数字开头和结尾
• 避免使用通用词：helper、assistant、agent

推荐：code-reviewer、test-generator、api-docs-writer 不推荐：ag（太短）、-start（以连字符开头）、my_agent（包含下划线）

步骤 2 — 编写 frontmatter

阅读 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md，了解完整的字段目录、颜色语义、模型选项、工具选择框架和执行修饰符。

必填： name、description 始终设置： model: inherit（除非需要特定模型能力）、color（在 UI 中用作视觉标识）

tools 的意图性规则： 将工具限制在最低所需范围，因为 Agent 会自主运行——权限过多时，没有人在环路中把关。分析任务使用 ["Read", "Grep", "Glob"]。生成内容时添加 Write。仅在 shell 执行不可或缺时添加 Bash，绝不要默认添加。 对于负责协调子 Agent 的会话模式 Agent，使用 Agent(type1, type2) 限定可启动的 Agent。

如果第 0 阶段确认适用，则设置：

• memory — 如果发现需要跨会话学习；在正文中添加记忆维护说明
• effort — 如果任务需要高于默认水平的思考深度
• initialPrompt — 如果这是一个应自动启动的会话 Agent
• background: true — 如果发现需要并发执行
• mcpServers — 如果发现需要使用外部工具

步骤 3 — 编写 description

每次会话都会将 description 字段加载到上下文中。Token 预算很重要——只写满足准确路由所需的最少内容。

使用 > 折叠标量，并包含：

• “在 [触发条件] 时使用此 Agent。”
• 适用时添加主动触发提示（例如：“建议在……后主动使用”）
• 范围边界（“不用于 X——请使用 Y-agent。”）
• 目标：50–70 个 token。不要使用 <example> 块——它们会浪费上下文，却不会改善路由效果。

步骤 4 — 编写系统提示词

Markdown 正文（--- 之后的内容）将成为 Agent 的系统提示词。全文使用第二人称，直接对 Agent 说话。这是与 skill 编写的关键区别：Agent 需要的是角色设定和流程，而不是给 Claude 遵循的指令。

标准结构：

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]

系统提示词的意图性规则：

• 角色设定优先——专家身份会影响后续所有决策；应在第一句中确立
• 流程步骤可防止复杂任务变成“临场发挥”；每一步都应设定明确的决策边界
• 输出格式不可妥协——调用方需要可预测的结构来处理结果
• 在系统提示词中定义边缘情况；运行时才发现错误会导致重试

如果设置了 memory： 添加一个章节，指导 Agent 维护其知识库： “发现代码路径、模式和关键架构决策时，请更新 Agent 记忆。开始工作前，请查阅记忆。” 这有助于跨会话学习。

正文应少于 3,000 个单词。详细的领域参考内容应放在 references/ 中，并通过 skills: frontmatter 字段预加载，而不是直接嵌入系统提示词。

请参阅 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md，查看展示主动触发模式的完整可用示例。

步骤 5 — 扫描脚本机会

阅读 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md，并将五种信号模式应用于 Agent 系统提示词中的每个步骤：

信号	问题	如果是 →
重复生成	是否有步骤会在多次调用中生成相同结构？	在 scripts/ 中编写参数化脚本
工具选择不明确	是否有步骤以脆弱的顺序组合使用工具？	将该流程编写为脚本
契约固定	你现在能否为此步骤编写 --help 文本？	CLI 候选项
双重用途潜力	用户是否会独立地从终端运行此步骤？	将其设计为规范的 CLI
一致性至关重要	相同输入是否必须始终产生完全相同的输出？	使用脚本——绝不要由 LLM 生成

步骤 6 — 检查委派

定稿前，检查现有的 Agent 和技能：

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

• 是否有现有的 Agent 涵盖此领域？扩展它，或收紧新 Agent 的范围
• 是否有技能或参考文件可通过 skills: frontmatter 预加载，以提供领域知识？
• 此 Agent 是否应该将子任务委派给某些命令或 MCP？

始终使用完全限定名称：

• Agent: subagent_type=plugin-dev:agent-creator（不要只写“agent-creator”）
• Skill: claude-skills:create-skill（不要只写“create-skill”）

步骤 7 — 验证

创建新的 Agent 文件时：

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

退出码 0 = 继续进入阶段 2。退出码 1 = 解析 errors 数组；每个条目包含 field、message、severity。写入磁盘前，解决所有 critical 和 major 项。

阶段 2：交付

输出路径

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

agents/ 中的 Agent 会自动发现，无需注册。插件 Agent 会自动使用命名空间 plugin-name:agent-name。

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

从头创建时：

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

退出码 0 = 已创建带占位符的文件，继续填写内容。 退出码 1 = 名称冲突；请用户重命名或确认覆盖。

说明你的选择

简要说明生成的 Agent 及其设计理由：

• 设置了什么以及原因 —“设置 model: sonnet，因为此 Agent 需要进行复杂的多文件推理”
• 排除了什么以及原因 —“未设置 isolation；无需管理 git 状态”
• 选择的工具及原因 — 明确说明每个工具的用途；无法说明理由的工具访问权限是设计缺陷

写入并确认

写入前：

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

创建后

总结：

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

继续进入阶段 3。

阶段 3：评估

维度	标准
清晰度（0-10）	系统提示词明确无歧义，目标和角色设定清晰
触发精准度（0-10）	描述和示例覆盖预期的触发范围，不超出范围
效率（0-10）	系统提示词的 token 利用率——每个 token 提供尽可能多的指导
完整性（0-10）	涵盖领域要求；定义输出格式；处理边界情况
安全性（0-10）	工具权限限制在最低必要范围内；不授予过宽的权限

目标：9.0/10.0。 如果低于此分数，针对最薄弱的维度进行一次优化，然后交付。

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

验证清单

结构：

• 文件是 agents/ 目录中的 <name>.md
• YAML 前置元数据有效，包含 name 和 description
• Markdown 正文存在且内容充实

描述质量：

• 以“Use this agent when...”开头
• 使用简洁的 > 标量，包含 50–70 个词，不含 <example> 块
• 说明范围边界（不适用于哪些情况）
• 如果 Agent 应在特定事件后触发，则包含主动触发提示

系统提示词质量：

• 使用第二人称（“You are...”“You will...”）
• 首句清晰说明角色或身份
• 流程步骤使用编号并采用祈使句
• 定义输出格式
• 说明边缘情况的处理方式
• 少于 3,000 个词；领域细节放入 references/

前置元数据：

• 除非需要特定模型，否则设置 model: inherit
• 设置 color，且颜色具有明确的语义
• 将 tools 限制为最低必要范围
• 如果需要跨会话学习，则设置 memory，并在正文中说明维护要求
• 如果需要非默认的思考深度，则设置 effort
• 如果会话模式的 Agent 会自行启动，则设置 initialPrompt
• 如果已确定需要并发执行，则设置 background: true
• 如果 Agent 修改的文件需要在合并前审核，则设置 isolation: worktree
• 不留任何 TODO 占位符

错误处理

问题	操作
领域不明确	询问：该 Agent 如何才算成功？
范围过宽	拆分为 2–3 个触发条件互不重叠的专注型 Agent
与现有 Agent 冲突	指出重叠之处；缩小触发范围或扩展现有 Agent
触发条件模糊	请提供 3 条应触发此 Agent 的具体用户消息