SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场writing-agents

writing-agents

智能体与模型

查看项目

更新于 10-15 11:02

技能介绍

用途

该技能用于指导编写 Claude Code 的代理（agent）——即通过 Task 工具调用的专用子代理角色定义。适用场景包括：创建新代理、编辑已有代理，以及为 Task 工具定义专用子代理角色。核心理念是：编写代理就是将测试驱动开发（TDD）应用于角色定义。如果未在代表性任务上测试过代理，就不知道它是否表现正确。文档要求使用前先理解 test-driven-development 和 writing-skills，因为同样适用 RED-GREEN-REFACTOR 循环。

代理与技能的区别

文档以对比表列出二者差异：调用方式上，代理用带 subagent_type 的 Task 工具，技能用带 skill name 的 Skill 工具；上下文上，代理获得完整对话历史，技能按需加载；执行上，代理自主、多轮，技能提供单次响应指导；角色上，代理有显式角色/身份，技能是参考文档；位置上，代理在 .claude/agents/，技能在 .claude/skills/；用途上，代理适合复杂自主任务，技能适合可复用模式与技术。

代理文件结构与创建工作流

代理是项目级的，位于项目的 .claude/agents/ 目录而非个人目录，每个代理是一个含 frontmatter 与人设的 .md 文件。frontmatter 为 YAML，包含 name、description、可选 model（opus、sonnet、haiku，默认继承父级）。创建或修改代理后，需提示用户重启 Claude Code 会话，因为代理在会话启动时加载。

创建工作流分四步：

  1. 调研领域最佳实践：用 WebSearch 查找领域特定指导，如“[领域] 开发最佳实践”“常见 [领域] 错误/反模式”“[领域] 代码审查清单”“[技术] 安全注意事项”，并将发现纳入反模式、最佳实践和安全注意事项部分。文档按领域给出示例搜索词，包括 Shell 脚本、Debian 打包、CI/CD、Electron/AppImage。
  2. 收集代码库上下文：读 CLAUDE.md 和 README.md 获取项目约定；用 Glob/Grep 识别与代理领域相关的目录结构、现有服务/控制器/模型、测试模式与约定；检查 .claude/agents/ 中已有代理，了解协作协议、委托关系和命名约定。文档给出探索示例命令。
  3. 撰写代理：结合调研与代码库上下文，写扎根于项目具体情况的角色人设、来自调研和项目历史的反模式、代理所需的项目结构与命令、与现有代理的协作方式。
  4. 重启会话：写完后告知用户代理已创建及路径，并提醒必须重启 Claude Code 会话；重启后该代理会出现在 Task 工具可用代理中，以 subagent_type 调用。

有效代理的组成

文档将有效代理拆解为五个部分：

  • 清晰人设定义：人设是代理的 DNA，写得越具体行为越一致。示例给出资深 shell 脚本与 Electron 打包专家的具体人设，反例是泛化的“有帮助的助手”。
  • 显式范围边界：定义代理做什么、不做什么，防止范围蔓延并支持委托给专家。列出核心能力与不在范围内（委托给某代理）的项目。
  • 反模式部分：列出要避免的具体错误，比泛泛指南更有效。示例包括不要硬编码压缩变量名、sed 模式中始终处理可选空白、条件判断用 [[ ]] 而非 [ ]、不要用 set -e 而用 || exit 1 显式处理错误。
  • 协作协议：定义代理如何与他人配合，多代理工作流必备。文档给出被委托时的确认、按需求实现、报告完成的流程及报告格式，包括问题/任务引用、所做更改、执行的测试和明确的“准备进入下一步”声明。
  • 项目上下文：提供相关项目结构、关键命令和约定，使代理能自主运行。文档以 claude-desktop-debian 为例展示目录树和 shellcheck、actionlint 等命令。

描述字段与模型选择

描述字段对 Task 工具路由至关重要，Claude 靠它选择正确的代理。格式为“[角色陈述]。用于 [特定任务类型]。”文档给出好的描述示例，如 shell 脚本与构建系统专家、GitHub Actions 的 CI/CD 工作流工程师（并委托构建专家处理 shell 脚本）、Debian 与 RPM 打包专家；坏描述包括过于含糊“帮助写代码”、没有触发条件、以及写入流程（会导致走捷径行为）。

模型选择按任务复杂度：haiku 用于快速直接任务，成本低；sonnet 用于平衡复杂度（默认），成本中；opus 用于深度推理与架构决策，成本高。省略 model 则继承父对话。

常见代理模式

  • 专家代理：聚焦单一领域，边界清晰，有委托规则。
  • 编排代理：协调其他代理、管理工作流，不做实现；管理任务分解与分配、进度跟踪、结果整合；不直接写代码、不做实现决策、未经批准不部署。
  • 审查代理：按标准评估工作并提供结构化反馈，输出状态（PASS/FAIL/NEEDS_CHANGES）、问题清单、建议清单。

测试代理

RED 阶段：用通用提示跑代表性任务，记录它会犯什么错误、缺少什么上下文、哪里出错。GREEN 阶段：写最小代理，针对基线的具体失败加人设、反模式和项目上下文。REFACTOR 阶段：测试边界情况，看它是否守住范围、是否正确委托、是否遵守协作协议。

创建清单与要避免的反模式

创建清单按阶段列出：调研阶段（检索最佳实践、反模式、安全注意事项并记录发现）、上下文阶段（读 CLAUDE.md/README、探索代码库、检查已有代理、识别协作/委托关系）、RED 阶段（识别专用任务类型、测基线、记录具体失败）、GREEN 阶段（清晰人设与项目上下文、显式范围、来自调研与项目经验的反模式、项目结构与命令、协作协议、合适的模型）、REFACTOR 阶段（在代表性任务上测试、验证范围边界、验证委托、验证协作协议）、质量检查（描述不超过 500 字符且含触发条件、人设具体、反模式可操作、描述中无流程总结）、部署（写入 .claude/agents/[name].md、提示用户重启会话）。

要避免的反模式包括：泛化人设（如“你是有帮助的助手”）、缺少范围边界（如“你可以帮助任何事”）、含糊的反模式（如“写好代码”“遵循最佳实践”）、在描述中写流程。

要点

代理是自主专家，需要清晰身份、显式范围、可操作指南和协作协议。要在真实任务上测试代理，定义明确的人设产生一致可靠的行为，含糊的人设产生不可预测的结果。文档末尾列出参考链接，涉及 AI 代理的提示工程与系统提示技巧。