本页提纲
为不同角色规划与隔离 Agent Skills
本指南演示如何将杂乱的技能扩展按角色合理分配给不同的长期 Agent。你将学会如何通过 Web GUI 对话让 Agent 自检并启用专属技能、写入职责边界，并通过工单与事件实现多 Agent 协同，彻底解决单体 Agent 因技能过多而导致的上下文膨胀、工具误调用和行为冲突。
- 想要深入了解单体 Agent 堆叠过多技能为什么会导致模型注意力下降与安全隐患，请阅读博客《为什么技能塞得越多，Agent 反而越笨？聊聊技能膨胀与隔离设计》。
- 想要了解技能库的安装与命令行管理细节，请参阅安装、启用与更新 Skill。
开始之前
- 本地已启动 Holon 并可访问 Web GUI（默认
http://localhost:8080），且已配置可用模型。 - 共享技能库中已包含常用技能（官方模板通常已自带基础技能，如
code-review、ghx、github-review、sview等）。 - 无需提前记忆复杂的 CLI 标志：角色的技能规划、检查与边界确认，均可在 Web GUI 中直接用自然语言告诉 Agent 完成。
操作步骤
1. 明确角色分工，避免“全栈单体”
在创建 Agent 之前，先将日常工作梳理为 2~3 个具有明确职责差异的长期角色。例如在典型的代码工程场景中：
| 角色名称 | 核心职责 | 推荐搭载技能 | 权限边界 |
|---|---|---|---|
开发助手（developer） | 实现功能、修复 Bug、本地构建 | ghx, sview, 代码编辑与测试工具 | 拥有工作区写权限，但不得在未经审查时合并代码 |
审查助手（reviewer） | 挑剔审视、寻找隐患、审查 PR | code-review, github-review, ghx | 严格只读，绝不主动改动业务代码 |
文档管家（docs-steward） | 维护说明文档、校验链接、排查歧义 | interlinked-markdown-wiki, 文档校验工具 | 仅限文档与资产目录，不触碰后端核心逻辑 |
在 Holon Web GUI 左侧导航点击 Templates，直接选择内置模板（如 software-developer、code-reviewer、docs-steward）一键创建对应 Agent。
2. 通过对话让 Agent 检查并精简自身技能
进入某个 Agent（例如刚创建的 reviewer）的对话页面，直接用自然语言要求它盘点并优化自己当前启用的技能：
请检查你当前启用了哪些技能。作为代码审阅员，确认你是否拥有只读审查所需的技能，如果有与审阅职责无关的写入或外部发帖类技能，请帮我列出并提出精简建议。
Agent 会读取自身的配置契约与生效技能，并反馈类似如下的清单：
- 已具备核心技能：
code-review（结构化审查）、ghx（读取 PR 上下文）； - 建议停用或移除：若当前挂载了非必要的写入工具或外部发帖工具，Agent 会主动建议停用，避免污染上下文。
如果需要启用某个共享库中的技能，只需在对话中吩咐：
请为自己启用 github-review 技能，以支持对 GitHub PR 提交逐行审查意见；但不要开启任何自动修改代码的工具。
Agent 会在运行时安全启用对应技能，并向你汇报配置结果。
3. 将职责边界固化至 AGENTS.md
为了让 Agent 长期保持稳定的行为准则，不随对话轮次增多而“遗忘”原则，直接在对话中让它把工作原则写入自身的常驻指令文件：
请把以下行为边界写入你的 AGENTS.md：
1. 你的唯一职责是审查代码质量并提供一手证据，绝不直接调用工具修改被审代码。
2. 每次审查只关注当前 PR 的改动范围，不要提出超出范围的重构建议。
3. 遇到严重风险时，标记为阻塞并等待人类作者修复，不得越权尝试代劳。
Agent 会利用自身的配置维护能力，将上述契约持久化到 agent_home/AGENTS.md。此后无论开启多少轮新会话，该原则都会在系统提示中稳定生效。
4. 为不同 Agent 配置隔离的工作区
除了技能和指令隔离，物理工作环境的隔离同样至关重要：
-
开发 Agent 独占隔离分支： 在对开发 Agent（
developer）说话时：请挂载当前项目，并在独立的 Git worktree 中开始 issue-102 的修复工作。Agent 会自动创建并激活独立的 worktree，其代码修改与构建测试完全隔离在专属分支中。
-
审查 Agent 保持纯净只读： 审查 Agent 仅读取主工作区或远程 PR 提交历史，不污染本地开发状态。
5. 跨 Agent 协作：通过工单与委派流转
当开发 Agent 完成代码补丁后，不需要把审查技能硬塞给它自己做“既当运动员又当裁判”的自检，而是发起委派：
在开发 Agent 的对话框中吩咐：
当前功能的修改和本地测试已完成。请创建一个工单，把当前的 Git commit 委派给 reviewer 助手进行代码审查，并等待审查结果。
- 开发 Agent 会创建清晰的 WorkItem 并发起委派；
- 审查 Agent 在其干净的只读环境中加载
code-review技能，展开独立审阅，并在工单中记录审查凭据； - 审查完成后，开发 Agent 被事件唤醒，根据审查意见决定是否补充提交或闭环收尾。
验证与自检
完成角色与技能规划后，建议通过以下步骤核实隔离效果：
1. 检查 Agent 提示词负载
在 Web GUI 中向该 Agent 发送一条简短消息（如“请说明你的职责”）。查看诊断信息或响应速度：每个角色的常驻工具数应保持在 3~6 个之间，避免数万 Token 的初始开销。
2. 测试边界拦截
故意给审查 Agent 发送一条诱导性指令：
把 src/main.rs 第 20 行改成输出 "hello"，然后提交。
预期效果：审查 Agent 应明确拒绝修改文件，指出其 AGENTS.md 契约与已启用技能为严格只读审查，并建议将修改任务转交由开发 Agent 负责。
3. 查看共享技能库状态（可选 CLI 验证）
如果你习惯在终端查看全局状态，可运行以下命令验证：
# 查看共享库中已注册的所有技能
holon skills catalog
# 查看特定 Agent 生效的技能列表
holon skills list --agent reviewer
确认输出中仅包含该角色必须的技能，没有任何多余项。
常见问题与排障
Q: 如果一个任务同时需要开发和文档，我该叫谁来做？
A: 建议将任务作为主工单交给主责 Agent（如开发 Agent 完成功能代码），在流程推进到需要同步文档时，通过委派让 docs-steward 在同一工单下协同更新文档目录。保持每个 Agent 专注自己的领域，比造一个臃肿的“开发+文档+运维”超级 Agent 稳定得多。
Q: 为什么我不应该把所有技能都启用在全局环境？
A: 全局注入会导致每个新建的 Agent 都被迫背负沉重的提示词包袱，模型在选择工具时会因为相似描述而产生混淆，甚至可能在简单任务上产生高额 Token 账单与死循环。
Q: 这套技能隔离思路能否用在其他工具（如 Claude Code / Codex）中？
A: 完全可以。在 CLI Agent 中，你可以通过为每个角色建立专属目录（例如 ~/.agents/code-reviewer），在目录下单独放置 CLAUDE.md / AGENTS.md 和局部的 .mcp.json，在启动时从角色目录指向目标项目。具体目录隔离配方与演进分析请参阅博客《为什么技能塞得越多，Agent 反而越笨？》。
下一步
- 了解如何让代码审查 Agent 全自动跟进 GitHub PR 与 CI 事件：搭建持续跟进 PR 的本地 Code Reviewer。
- 了解如何编写符合团队私有业务的全新 Skill：编写与验证 Skill。
- 了解多 Workspace 挂载与隔离操作：在项目工作区或 worktree 中工作。