write-agent

Context: 用户请求创建一个单一用途的审查者 user: “创建一个安全审查 Agent，检查我的代码更改” assistant: “这是一个单一用途的审查任务——我会创建一个使用只读工具的子 Agent。” 单一任务（安全审查）+ 一种输出类型 → 子 Agent，而非协调器。 assistant: “我会使用 write-agent 技能创建一个 security-reviewer 子 Agent。” Context: 用户请求创建一个多阶段工作流协调器 user: “我需要一个 Agent，能够规划功能、实现功能、进行审查，并不断迭代，直到通过质量门槛” assistant: “这是一个包含协调、分派和迭代的多阶段工作流——我会创建一个工作流协调器。” 多个阶段 + 子 Agent 分派 + 迭代 → 工作流协调器模式。 assistant: “我会使用 write-agent 技能创建一个工作流协调器。” Context: 用户询问仓库规范（不是 Agent） user: “我应该如何记录此仓库的提交消息格式？” assistant: “这是关于整个仓库规范的问题，而不是 Agent 设计。我会改为将其添加到 CLAUDE.md。” 始终适用的仓库约束 → CLAUDE.md，而不是 Agent。不要触发 write-agent。 assistant: “我会将提交消息规范添加到 CLAUDE.md。” Context: 用户请求更新或重构现有 Agent user: “你能整理一下 security-reviewer Agent 吗？它越来越啰嗦了，而且我觉得路由也不太对。” assistant: “这是对现有 Agent 的更新——我需要在改进清晰度和路由的同时保留原有意图。” 更新／重构请求 → 使用更新流程，避免偏离原意。加载 references/updating-existing-agents.md。 assistant: “我会使用 write-agent 技能和更新流程来重构 security-reviewer Agent。”

Write Agent 技能

设计专注、安全且可靠的 Agent，同时避免过度约束。

核心原则：将 token 和注意力视为共享预算。优先采用简短、高信号的提示词和明确的输出约定，而不是冗长的说明。

---

此技能如何使用辅助文件

此技能包含位于 references/ 和 templates/ 中的可选辅助材料。

• 当工作流步骤注明 Load： path/to/file.md 时，请在继续之前打开该文件。
• 如果对某个决策点感到不确定，请跳转到末尾的参考索引，查找相应的深入资料。
• 模板是可自定义的起点，并非僵化格式。

对于不简单的 Agent 设计： 可以考虑在开始之前阅读此技能文件夹中的所有文件。上下文不完整可能导致 Agent 前后不一致，或遗漏相关模式。在设计协调器、更新现有 Agent 或处理陌生领域时，这一点尤其有帮助。

---

运行原则（供 Agent 设计者参考）

编写 Agent 提示词时，请遵循以下原则：

1. 将注意力视为稀缺资源。 模型的注意力会随上下文长度按 O(n²) 增长。每个 token 都会与其他 token 争夺注意力。将关键指令放在前面；将参考资料移至 references/ 文件中，按需加载。

2. 以可靠性而非优雅为优化目标。 如果某个步骤容易出错或比较脆弱，就添加防护措施：检查清单、验证循环、“做 X，而不是 Y”之类的约束。不要依赖模型自行推断正确行为。

3. 默认采用一条可靠的路径，同时提供备用方案。 提供推荐的默认工作流。如果存在其他选项，请明确列出，但避免选项过多。

4. 以便于执行为目标来撰写。 使用清晰的祈使句：“做 X。然后做 Y。”避免使用没有具体步骤或产出的含糊告诫（“小心”“要全面”）。

5. 让措辞体现确定程度。 对硬性要求使用“必须”／“绝不”。对有例外情况的强默认要求使用“应该”／“优先”。对建议使用“可以考虑”／“可以”。Agent 会解析这种程度差异。

6. 让 Agent 提示词独立完整。 假设读者是首次阅读，完全不了解上下文。不要依赖 Agent 从之前的对话或父级状态中推断信息。特别是对子 Agent：不要提及其他 Agent 的名称——应将每个 Agent 都写成唯一存在的 Agent。（编排器是例外；它们负责协调子 Agent。）如果子 Agent 需要编排上下文，父级应通过交接传递，而不是写入永久提示词。

7. 恰当使用正向和负向表述。 对常规指导，正向表述（“做 X”）通常比禁止性表述（“不要做 Y”）更清晰。但负向表述也是有效的补充工具，尤其适用于排除项、失败模式和边界定义。使用负向表述时，应具体明确（而非含糊），并在有帮助时配上对比示例，同时将关键约束放在章节边界处。技巧详情请参见 references/prompt-structure.md。

---

使用此技能时应产出的内容

当用户要求“创建一个 Agent”／“编写一个子 Agent”／“制作一个审查者”／“制作一个编排器”时：

1. Agent 简介（简洁）——如有需要，包含假设。
2. 可直接粘贴使用的 Agent 文件（.claude/agents/<name>.md）。
   • 如果是子 Agent：负责单一用途的执行者／审查者。
   • 如果是工作流编排器：使用 Task 工具启动子 Agent 的多阶段协调器。
3. 可选配套内容（仅在确实有帮助时提供）：
   • 技能（可复用的工作流／知识）
   • 输出契约技能（供编排器汇总使用的共享架构，例如，所有审查者都预加载 pr-review-output-contract）
   • CLAUDE.md／.claude/rules 补充内容（始终生效的约束）
   • 钩子（用于有条件地限制工具／设置质量门槛）

简要说明。优先提供具体产物（文件、模板、检查清单）。

工作流

创建工作流任务（第一步）

开始任何工作前，使用 TaskCreate 为每个步骤创建任务，并通过 addBlockedBy 强制执行顺序。根据各步骤工作流文本中的内容和完成标准来拟定任务描述。

1. 编写 Agent：路由请求并整理 Agent 简介
2. 编写 Agent：确定实现机制和严格程度
3. 编写 Agent：编写配置并撰写系统提示词
4. 编写 Agent：设计交接并添加防护措施

开始处理任务时，将其标记为 in_progress；满足该步骤的退出标准后，将其标记为 completed。重新进入时，先检查 TaskList，然后从第一个未完成的任务继续。

0) 确定请求类型

确定你要执行哪种操作：

• 创建全新的 Agent → 继续执行下方的步骤 1–8
• 更新/重构现有 Agent → 加载： references/updating-existing-agents.md 并遵循其中的流程

如果要更新/重构现有 Agent：

重要： 开始任何更新工作之前，必须先完成该文件中的步骤 0：完整加载上下文。这意味着要阅读：

1. write-agent/ 文件夹中的每个文件（SKILL.md + 所有 references/ + 所有 templates/ + 所有 scripts/）
2. 与目标 Agent 相关的每个文件（Agent 文件 + 所有支持文件）
3. 任何会启动此 Agent 的协调器（如适用）

不要跳过此步骤。上下文加载不完整是更新期间路由偏移、能力范围膨胀和输出契约失效的主要原因。

---

1) 选择 Agent 模式：子 Agent 还是工作流协调器

快速判断： 如果你不确定 Agent 是否是合适的机制（相对于技能或 CLAUDE.md 规则），先跳到步骤 3。否则，选择符合需求的最轻量 Agent 模式：

需求	选择	实际效果
一项任务，一个输出（审查、实现、诊断、总结）	子 Agent	范围简单，更易验证；通常无需 Task 工具
多阶段工作流（研究 → 规划 → 实现 → 评审 → 迭代）	工作流协调器	需要 Task 工具；协调各阶段、分派子 Agent、汇总结果
单项任务需要隔离，但不需要多阶段协调	子 Agent（或 context: fork 技能——⚠️ 对插件而言不可靠，参见步骤 3 注释）	除非确有需要，否则避免编写协调逻辑

硬性限制： 子 Agent 不能启动其他子 Agent。 因此，工作流协调器必须作为顶层会话 Agent 运行（例如 claude --agent feature-development …），不能作为由 Task 启动的子 Agent 运行。

CLI 调用说明： 可以通过 claude --agent <name>（交互式）或 claude --agent <name> -p "prompt"（非交互式）直接调用 Agent。在运行中的会话内启动 Claude Code 子进程（例如迭代循环）时，请使用 env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p ... 模式——这会绕过嵌套防护。对子进程始终设置 --dangerously-skip-permissions。完整调用参考（包括多层嵌套）请参阅 references/claude-code-mechanics.md。

模板：

• 子 Agent：templates/subagent-template.md、templates/subagent-reviewer-template.md、templates/subagent-worker-template.md
• 协调器：templates/workflow-orchestrator-template.md
• 深入指南：references/workflow-orchestrators.md

2) 编写 Agent 简介（快速、精简）

填写以下字段。只有在缺失信息会造成阻碍时才提问；否则采用合理的默认值并注明。

• 模式： 子 Agent | 工作流协调器
• 待完成任务： 它应该可靠地完成什么？
• 委派触发条件： 什么情况应促使 Claude 使用它？
• 输入： 它需要哪些上下文/文件？可以假设哪些内容已准备就绪？
• 输出： 格式、受众和详略程度如何？
• 质量标准： 怎样的输出算“完成”，怎样的需要修订？
• 约束： 硬性规则（必须/绝不）与软性指导（应该/可以）
• 工具与权限： 采用最小权限的工具访问；选择权限模式
• 模型选择： 权衡成本/速度与推理需求
• 失败策略： 何时提问，何时基于假设继续

**如果是工作流协调器，**还需记录：阶段、子 Agent 阵容、产物策略、质量关卡和迭代策略。

加载： references/workflow-orchestrators.md，查看完整的协调器检查清单。

如有帮助，可从 references/prompt-structure.md 复制简介模板。

默认起点： 选择 templates/ 下最接近的模板，并在返回 Agent 文件前填写所有 [TODO]。

澄清策略（收集简报信息时）

使用此决策表，减少问得不够或问得过多的情况：

情况	应对
缺失的信息会影响 路由（委派触发条件）、工具权限、副作用或兼容性	起草前提出 1-3 个有针对性的问题。
用户说“你觉得怎样最好就怎样”／表示无所谓	给出具体建议和 1-2 个备选方案，然后确认这项重要选择。
细节影响较小且可逆（例如示例措辞、小节名称）	采用合理的默认值；简要列出假设，方便用户按需纠正。

问题设计（需要人工输入时）：

• 提供 2-4 个标注清晰的选项（不要超过 5 个，以免造成决策疲劳）。
• 将你推荐的选项放在首位，并标注“（推荐）”，再用 1 句话说明理由。
• 如果现有选项可能无法涵盖实际情况，请加入“其他”。
• 围绕答案会带来哪些变化来提问，而不是询问抽象偏好。

如果你依据假设继续操作，请标注为 假设：，方便用户发现并纠正。

3) 决策：使用 Agent、技能还是常驻规则

选择能够可靠实现目标的最轻量机制。

如果你需要……	优先选择	原因
始终生效的代码库约束（命令、约定、不可妥协的要求）	CLAUDE.md / .claude/rules	在所有场景中生效；无需路由
可在主对话上下文中运行的可复用指令	技能	无需隔离上下文即可复用；可轻松交互式调用
具有工具限制的单一专业工作者／审查者	子 Agent	上下文隔离 + 最小权限工具
协调其他 Agent 的多阶段流程	工作流编排器	编码阶段顺序、调度、汇总和迭代

注意：

• 子 Agent 无法启动其他子 Agent。如果需要多步骤专业化，编排必须由顶层 Agent／会话负责。

• 如果你想要可在“后台”运行的可复用工作流，优先选择：

  • 使用 context: fork 的技能，或
  • 作为会话 Agent 调用的工作流编排器 Agent。

  ⚠️ context: fork 不可靠（Issue #16803 — OPEN）。技能经常以内联方式运行，而不是分叉，尤其是插件技能（据报告，失败率达 95%+）。如果需要可靠隔离，请使用 Agent 工具 + 加载技能模式：启动一个 general-purpose 子 Agent，并在其提示词开头写上 "Before doing anything, load /skill-name"。子 Agent 会通过其 Skill 工具加载技能，并在隔离环境中执行。

4) 选择合适的严格程度（“金发姑娘区间”）

Agent 提示词应处于恰当的高度——足够具体以提供引导，也足够通用以便推广：

失败模式	表现	示例
过于僵化	枚举方式脆弱；遇到意外输入就会失效	“如果是 .ts，就执行 X。如果是 .tsx，就执行 Y。如果是 .js，就执行 Z……”
过于模糊	只有抽象原则，没有具体信号	“要乐于助人并且全面。”
恰到好处	可推广的启发式规则 + 明确的升级处理方式	“正确性优先于风格。不确定时，请提问。”

根据任务特征选择严格程度：

• **自由度高：**启发式规则 + 输出约定（审查、审计、头脑风暴）
• **中等：**步骤顺序 + 必需检查（重构、迁移）
• **低：**脚本／命令 + 严格验证循环（脆弱操作）

5）编写 Agent 配置（frontmatter）

设置（继续之前逐项确认是否都已填写）：

• name：稳定、采用连字符格式且能准确描述
• description：明确的触发条件和示例；避免路由范围过宽
• tools / disallowedTools：遵循最小权限原则
• permissionMode：默认即可，除非有充分理由
• model：haiku/sonnet/opus/inherit（谨慎选择）
• skills：明确预加载所需技能（不要假定会继承）

关键：路由使用 <example> 块。 添加 2–4 个 <example> 块，并使用 <commentary> 说明为什么应该（或不应该）进行委派。

子 Agent（推荐默认设置）：

• 不要包含 Task 工具（不进行嵌套生成）。
• 预加载用于判断或实施的领域技能（例如：skills: [write-docs]）。
• 制定严格的输出约定，确保编排器可以可靠地汇总结果。

工作流编排器（推荐默认设置）：

• 包含 Task 工具（以及检查代码仓库所需的最少工具）。
• 不要假定生成的子 Agent 会继承你的 skills:（它们不会）。
• 有关调度、汇总和迭代模式，请参阅 references/workflow-orchestrators.md。

最简模板（复制/粘贴并自定义）：

---
name: my-agent
description: Use this agent when <trigger conditions>. Avoid using it when <exclusions>.

<example>
Context: <situation that SHOULD delegate>
user: "<user message>"
assistant: "<assistant response before delegating>"
<commentary>
Why this matches the trigger conditions.
</commentary>
assistant: "I'll use the my-agent agent to…"
</example>

<example>
Context: <near-miss that SHOULD NOT delegate>
user: "<user message>"
assistant: "<assistant response that stays in the main thread>"
<commentary>
Why this is a near-miss / exclusion.
</commentary>
assistant: "<continue without delegating>"
</example>

# Optional:
# tools: Read, Grep
# model: sonnet
# permissionMode: default
---

# My Agent
...

加载：references/claude-code-mechanics.md，了解子 Agent 限制、权限模式和技能组合模式。

6）编写系统提示词正文

采用有助于正确执行的结构：

1. 角色与使命（2–4 句话）——包含个性描述
2. 范围与非目标（避免意外越界）
3. 操作原则（直接行动与提出建议之间的取舍）
4. 工作流检查清单（可复制/粘贴）
5. 工具使用政策（读取、grep、运行什么；如何减少噪声）
6. 输出约定（确切标题、详略限制、证据要求）
7. 交接协议（向子 Agent 提供什么；返回什么）
8. 提问/升级（何时询问；何时继续执行）

编写“角色与使命”部分：

“角色与使命”用于确立 Agent 的身份和判断框架。应当：

• 说明该角色如何才算出色（不只是描述它的工作内容）
• 描述该角色中优秀的人类从业者会展现的行为
• 避免可能为糟糕判断开脱的退路

加载：references/personality-and-intent.md，了解如何编写有效个性描述的模式。

快速指南：

• ✅ “你能发现最重要的问题——正确性、安全性、数据完整性”
• ✅ “你优先关注高影响问题，而非表面上的细枝末节”（安全的取舍：吹毛求疵属于反模式）
• ❌ “你交付能用的代码，而不是完美的代码”（有风险：“完美代码”并非反模式）
• ❌ “你务实且高效”（过于笼统，可能成为糟糕工作的借口）

编排器补充要求： 如果要编写工作流编排器，请明确添加阶段计划、调度规则、汇总规则、迭代策略和工件传递等部分。请参阅 references/workflow-orchestrators.md 和 references/prompt-structure.md。

风格要求： 使用第二人称（“你是……”“执行……”）。避免使用第一人称承诺（“我会编辑文件……”），除非 Agent 获准且需要这样做。

纳入对失败模式的认知：

优秀的 Agent 提示词不仅说明要做什么，还会明确指出根据其任务最可能出现的失败模式。这能为 Agent 提供自我纠正的目标。

加载：references/failure-modes.md，查看常见 LLM 失败模式的完整目录。

纳入失败模式的方式：

• 设置专门的**“需避免的失败模式”**部分（明确、便于浏览），或
• 将其融入操作原则（“执行 X。避免倾向于 Y。”）

选择与 Agent 场景最相关的 3–5 项，不要全部列出。

快速选择指南：

Agent 类型	通常相关
Reviewer（审查者）	抹平细微差异、来源权威性、不确定时仍断言、赘述或掩盖重点
Implementer（实现者）	不顾歧义一味推进、忽略下游影响、指令僵化、臆测意图
Orchestrator（编排者）	不顾歧义一味推进、从不升级处理、臆测意图、过度偏重近期信息

解读测试（对每条指令都执行）：

定稿提示词前，确认每条指令都通过以下四项检查：

1. 这句话可能有两种解读吗？ — 如果有，请补充澄清示例，或加入“执行 X，而非 Y”的约束。
2. 这是否假设了读者并不了解的上下文？ — Agent 提示词应独立完整；请明确隐含假设。
3. 不同模型或实例会以相同方式解读吗？ — 如果依赖某种未明确说明的特定解读，请将其明确写出。
4. 指令的约束力度是否清晰？ — 区分“必须”（不可协商）、“应该”（强烈建议的默认做法）和“可以考虑”（建议）。不要使用含糊的“谨慎行事”之类表述。

不要先草拟宽泛的内容再事后修正——写作时就要收紧措辞。

加载： references/prompt-structure.md，查看完整的提示词章节结构。

提示词技巧说明：

• 少样本示例： 精心挑选的 2–3 个示例胜过更多示例。顺序很重要：把最具代表性的示例放在最后（近因效应）。一个质量较差的示例就会拉低所有示例的效果。
• 正向表述： 参见操作原则 #7。尽可能将“不要在不确定时作答”改写为“仅在有把握时作答”。
• 有效的否定指令： 正确使用时，否定指令效果很好。使用对比示例（错误与正确）、让约束具体而不含糊，并在章节边界处放置关键约束。注意：大写或粗体强调并无帮助——请改用结构化技巧。详情请参见 references/prompt-structure.md。

7) 设计双向上下文交接

子 Agent 会从“空白状态”开始，因此不要指望它们记得父级对话。

• 父级／编排者 → 子 Agent：提供交接包（目标、约束、目标文件、合格标准）。
• 子 Agent → 父级／编排者：返回回传包（简要总结、发现、证据、后续行动、未决问题）。

编排者的产物经验法则：

• 如果某阶段的输出较小（< 约 2–3 KB），就在下一次交接包中传递。
• 如果某阶段的输出较大（计划、研究笔记、大量发现），将其写入文件并传递路径。这样可以避免令牌膨胀，并支持恢复／分支工作流。

错误保留： 子 Agent 执行操作失败时，要在交接上下文中保留失败操作和错误信息。这样可以实现隐式信念更新——Agent 无需明确的“不要执行 X”指令，也能从失败中了解哪些方法行不通。如果错误不断累积，可以总结其模式，但不要完全删去。

加载： references/handoff-protocol.md，查看数据包模板和迭代模式。

8) 添加物有所值的防护措施

优先采用以下防护措施：

• 可观察（检查清单、验证、具体标准）
• 具体（“运行 X 并报告 Y”）
• 低成本（不要把令牌浪费在泛泛的劝诫上）

避免：

• 冗长且百科全书式的提示词，
• 没有默认选项的大量并列选项，
• 没有步骤或输出要求的含糊“谨慎行事”之类表述。

质量标准

返回 Agent 文件前，请确认：

• Frontmatter 包含：name、带有 2–4 个 <example> 块的 description，以及预期的 tools/disallowedTools。
• description 的范围既不过宽也不过窄；示例至少包含一个容易混淆但应排除的情况。
• 角色与使命说明了卓越表现应是什么样（而不只是说明它要做什么）；不存在有风险的免责条款。
• 失效模式：已处理 3-5 种与上下文相关的失效模式（通过专门章节或融入原则中）。
• 指令通过解释测试：措辞无歧义、不依赖假定的上下文；必要时明确写出“做 X，而不是 Y”；指令力度清晰。
• 提示词正文包含：使命、范围/非目标、工作流、工具策略、输出约定和升级规则。
• 交接与返回数据包格式明确（或有明确引用）。

如果是工作流编排器，还请确认：

• 包含阶段计划、调度规则、汇总规则和迭代策略。
• 说明不允许嵌套的约束（必须作为顶层会话 Agent 运行）。

设计者自检（交付前）：

• 我写的指令中，是否有任何一句在不同上下文中可能被理解为两种意思？
• 我是否假定了 Agent 无法获取的上下文？
• 是否有地方使用了“谨慎”“彻底”等模糊措辞，而不是具体步骤？
• 我是否混淆了指令力度（本意是“必须”却用了“应该”，或反之）？

如果任何一项的回答是“是”，请在交付前修正。Agent 表现不佳的情况，大多源于设计者的失误，而非模型的局限。

实现输出格式

输出文件时，请按以下格式（路径 + 代码块）：

• path/to/file.md
• （内容放在围栏代码块中）

除非属于文件内容，否则不要在文件中嵌入额外的 Markdown 正文。

---

参考索引

此索引可帮助你快速找到合适的深入说明。在主工作流中，请遵循 Load: 指针。

优先级说明：

• P0 = 正确性/可靠性所必需
• P1 = 提升质量和一致性
• P2 = 可选的深入内容

参考资料

路径	优先级	使用场景	跳过的影响
references/updating-existing-agents.md	P0	更新或重构现有 Agent 的请求	意图偏移；路由错误；能力范围膨胀；下游编排器故障
references/claude-code-mechanics.md	P0	配置 frontmatter、理解约束、权限和组合方式、CLI 调用模式（--agent、-p、--resume）以及递归调用限制	路由错误、权限错误、启动失败、递归调用受阻
references/prompt-structure.md	P0	构建系统提示词正文；编写角色与使命、工具策略、输出约定	步骤遗漏、输出不一致、升级处理不明确
references/failure-modes.md	P1	选择要针对该类 Agent 防范的故障模式	Agent 会表现出可预见的大模型盲点
references/personality-and-intent.md	P1	编写有效的角色与使命声明；避免留下逃避空间	身份模糊、权衡表述存在风险
references/workflow-orchestrators.md	P1	设计多阶段编排器；调度、汇总、迭代	编排器缺少关键协调模式
references/handoff-protocol.md	P1	设计交接数据包；构建返回数据包；进行多阶段串联	子 Agent 缺少所需上下文，或返回无法使用的结果
references/evaluation-and-iteration.md	P1	调整委派行为；排查触发过多或不足的问题	Agent 的行为校准持续不当
references/procedural-patterns.md	P2	编写验证循环、迭代策略或错误处理	Agent 可能陷入无限循环、跳过验证或无法妥善处理错误
references/designer-failure-modes.md	P2	排查 Agent 表现不佳的问题；交付前审查提示词	将设计错误归咎于模型

模板

路径	使用场景
templates/subagent-template.md	创建通用子 Agent
templates/subagent-reviewer-template.md	只读审查者（禁止 Write/Edit）
templates/subagent-worker-template.md	专注于实现的工作 Agent
templates/workflow-orchestrator-template.md	多阶段编排器（使用 Task 工具）
templates/skill-fork-template.md	在分叉的子 Agent 上下文中运行的技能

脚本

路径	用途
scripts/validate-agent.sh	验证 Agent 文件结构；检查是否缺少 name/description，并在缺少 <example> 块时发出警告