用途
writing-agents 用于在 Claude Code 中创建新的智能体、编辑已有智能体，或为 Task 工具定义专门的子智能体角色。文档将智能体定义视为一种测试驱动开发（TDD）实践：智能体是通过 Task 工具调用的专门子智能体，会接收完整对话上下文，并以既定人设、工具和行为准则自主执行。核心原则是：如果没有在代表性任务上测试过智能体，就不知道它是否正确工作。使用前需要先理解 test-driven-development 和 writing-skills，同样适用 RED-GREEN-REFACTOR 循环。
智能体与技能的区别
文档以对照方式说明两者差异：调用方式上，智能体通过 Task 工具的 subagent_type 调用，技能通过 Skill 工具的 skill name 调用；上下文上，智能体获得完整对话历史，技能按需加载；执行上，智能体自主、多轮，技能提供单次响应指导；人设上，智能体有明确角色/身份，技能是参考文档；位置上，智能体位于 .claude/agents/，技能位于 .claude/skills/；适用上，智能体用于复杂、自主的任务，技能用于可复用的模式与技术。
智能体文件结构
智能体是项目级的，存放在项目的 .claude/agents/ 目录，而非个人目录。每个智能体是单个 .md 文件，包含 frontmatter 与人设内容。frontmatter 为 YAML 格式，字段包括 name（名称）、description（角色描述，写明用于哪些具体任务类型）、model（可选：opus、sonnet、haiku，默认继承父级）。文档特别提示：创建或修改智能体后，需要提示用户重启 Claude Code 会话，因为智能体在会话启动时加载，重启前不可用。
创建流程
第一步：调研领域最佳实践。使用 WebSearch 查找领域相关指导，例如“[领域] 开发最佳实践”“[领域] 常见错误/反模式”“[领域] 代码审查清单”“[技术] 安全注意事项”。文档按领域给出示例搜索词，包括 Laravel 后端、React 前端、DevOps/基础设施、数据库等，并将发现融入反模式、最佳实践和安全注意事项部分。
第二步：收集代码库上下文。阅读 CLAUDE.md 和 README.md 了解项目约定；用 Glob/Grep 识别现有模式，包括与智能体领域相关的目录结构、现有服务/控制器/模型、测试模式与约定；检查 .claude/agents/ 中已有智能体，了解需要遵循的协作协议、需要建立的委派关系和命名约定。
第三步：撰写智能体。将调研结果与代码库上下文结合，形成扎根于项目具体情况的角色人设、来自调研和项目历史的反模式、智能体所需的项目结构与命令、与现有智能体的协作方式。
第四步：会话重启。写完文件后告知用户智能体已创建，并提示必须重启 Claude Code 会话才能使用；重启后该智能体会出现在 Task 工具的可用智能体列表中，通过 subagent_type 调用。
有效智能体的组成要素
清晰的人设定义：人设是智能体的 DNA，应写明具体角色、专长领域、具体能力和项目上下文。文档给出好坏示例对比，好的人设如“资深 PHP/Laravel 后端开发者，深耕 Laravel、PHP 与服务端架构，专为某平台构建健壮可扩展的后端系统”，坏的人设如“你是一个乐于助人的助手”。
明确的范围边界：定义智能体处理什么、不处理什么，防止范围蔓延并支持向专家委派。文档建议用 CORE COMPETENCIES 列出能力，用“Not in scope（委派给某智能体）”列出排除领域。
反模式部分：列出要避免的具体错误，比泛泛的指导更有效，例如始终用 with() 预加载关系防止 N+1、大表上不要用 Model::all() 而要用分页、配置文件外不要调用 env() 而要用 config()。
协作协议：定义智能体如何与其他智能体协作，对多智能体工作流至关重要，包括被委派任务时的确认、按需求实现、带具体细节报告完成情况，以及报告格式（问题/任务引用、所做更改、执行的测试、明确的“可进入下一步”声明）。
项目上下文：提供相关项目结构、关键命令和约定，使智能体能自主运行。
description 字段写法
description 对 Task 工具的路由至关重要，Claude 用它选择正确的智能体。格式为“[角色陈述]。用于[具体任务类型]。”文档给出好的示例（具体角色加清晰触发条件、清晰范围加委派、领域专长）和坏的示例（过于模糊、没有触发条件、把流程写进描述导致走捷径行为）。
模型选择
文档给出模型选择建议：haiku 用于快速、直接的任务，成本低；sonnet 用于平衡复杂度（默认），成本中等；opus 用于深度推理和架构决策，成本高。省略 model 则继承父对话。
常见智能体模式
专家型智能体：聚焦单一领域，有清晰边界和委派规则。编排型智能体：协调其他智能体、管理工作流，不直接做实现，负责任务拆解与分配、进度跟踪、结果整合，不写代码、不做实现决策、未经批准不部署。审查型智能体：按标准评估工作并给出结构化反馈，输出包含状态（PASS/FAIL/NEEDS_CHANGES）、问题列表和建议列表。
测试智能体
RED 阶段：用通用提示运行代表性任务，记录它犯的错误、缺失的上下文、出错的地方。GREEN 阶段：编写最小智能体，针对基线失败点补充人设、反模式和项目上下文。REFACTOR 阶段：测试边界情况，检查它是否守住范围、是否正确委派、是否遵循协作协议。
创建检查清单
文档提供分阶段清单：调研阶段（搜索领域最佳实践、反模式、安全注意事项并记录发现）、上下文阶段（阅读项目约定文件、探索代码库、检查已有智能体、识别协作/委派关系）、RED 阶段（识别专门任务类型、测试无智能体时的基线行为、记录具体失败与缺口）、GREEN 阶段（清晰人设、明确范围边界、来自调研和项目经验的反模式、项目结构与命令、多智能体时的协作协议、合适的模型选择）、REFACTOR 阶段（在代表性任务上测试、验证范围边界、验证委派、验证协作协议）。质量检查包括：description 在 500 字符以内且包含触发条件、人设具体而非泛泛、反模式可操作而非模糊、描述中不含流程总结。部署时写入 .claude/agents/[name].md 并提示用户重启会话。
适用场景与限制
该技能适用于为 Claude Code 项目定义专门子智能体角色的场景，尤其是需要多智能体协作、明确职责边界和委派关系的复杂项目。文档强调智能体是自主专家，需要清晰身份、明确范围、可操作指南和协作协议，并应在真实任务上测试。限制方面：智能体为项目级、需重启会话才生效；文档未提供具体的收费、价格或平台支持信息。