---
title: 为不同角色规划与隔离 Agent Skills
summary: 避免工具泛滥与指令互斥：通过自然语言为不同长期 Agent 分配专属技能、工作边界与权限，保持上下文干净。
order: 89
---

# 为不同角色规划与隔离 Agent Skills

本指南演示如何将杂乱的技能扩展按角色合理分配给不同的长期 Agent。你将学会如何通过 Web GUI 对话让 Agent 自检并启用专属技能、写入职责边界，并通过工单与事件实现多 Agent 协同，彻底解决单体 Agent 因技能过多而导致的上下文膨胀、工具误调用和行为冲突。

- 想要深入了解单体 Agent 堆叠过多技能为什么会导致模型注意力下降与安全隐患，请阅读博客[《为什么技能塞得越多，Agent 反而越笨？聊聊技能膨胀与隔离设计》](../blog/why-agents-need-skill-isolation.md)。
- 想要了解技能库的安装与命令行管理细节，请参阅[安装、启用与更新 Skill](./use-skills.md)。

## 开始之前

- 本地已启动 Holon 并可访问 [Web GUI](./use-web-gui.md)（默认 `http://localhost:8080`），且已[配置可用模型](./configure-models.md)。
- 共享技能库中已包含常用技能（官方模板通常已自带基础技能，如 `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`）的对话页面，直接用自然语言要求它盘点并优化自己当前启用的技能：

```text
请检查你当前启用了哪些技能。作为代码审阅员，确认你是否拥有只读审查所需的技能，如果有与审阅职责无关的写入或外部发帖类技能，请帮我列出并提出精简建议。
```

Agent 会读取自身的配置契约与生效技能，并反馈类似如下的清单：
- **已具备核心技能**：`code-review`（结构化审查）、`ghx`（读取 PR 上下文）；
- **建议停用或移除**：若当前挂载了非必要的写入工具或外部发帖工具，Agent 会主动建议停用，避免污染上下文。

如果需要启用某个共享库中的技能，只需在对话中吩咐：

```text
请为自己启用 github-review 技能，以支持对 GitHub PR 提交逐行审查意见；但不要开启任何自动修改代码的工具。
```

Agent 会在运行时安全启用对应技能，并向你汇报配置结果。

### 3. 将职责边界固化至 `AGENTS.md`

为了让 Agent 长期保持稳定的行为准则，不随对话轮次增多而“遗忘”原则，直接在对话中让它把工作原则写入自身的常驻指令文件：

```text
请把以下行为边界写入你的 AGENTS.md：
1. 你的唯一职责是审查代码质量并提供一手证据，绝不直接调用工具修改被审代码。
2. 每次审查只关注当前 PR 的改动范围，不要提出超出范围的重构建议。
3. 遇到严重风险时，标记为阻塞并等待人类作者修复，不得越权尝试代劳。
```

Agent 会利用自身的配置维护能力，将上述契约持久化到 `agent_home/AGENTS.md`。此后无论开启多少轮新会话，该原则都会在系统提示中稳定生效。

### 4. 为不同 Agent 配置隔离的工作区

除了技能和指令隔离，物理工作环境的隔离同样至关重要：

1. **开发 Agent 独占隔离分支**：
   在对开发 Agent（`developer`）说话时：
   ```text
   请挂载当前项目，并在独立的 Git worktree 中开始 issue-102 的修复工作。
   ```
   Agent 会自动创建并激活独立的 worktree，其代码修改与构建测试完全隔离在专属分支中。

2. **审查 Agent 保持纯净只读**：
   审查 Agent 仅读取主工作区或远程 PR 提交历史，不污染本地开发状态。

### 5. 跨 Agent 协作：通过工单与委派流转

当开发 Agent 完成代码补丁后，不需要把审查技能硬塞给它自己做“既当运动员又当裁判”的自检，而是发起委派：

在开发 Agent 的对话框中吩咐：
```text
当前功能的修改和本地测试已完成。请创建一个工单，把当前的 Git commit 委派给 reviewer 助手进行代码审查，并等待审查结果。
```

1. 开发 Agent 会创建清晰的 WorkItem 并发起委派；
2. 审查 Agent 在其干净的只读环境中加载 `code-review` 技能，展开独立审阅，并在工单中记录审查凭据；
3. 审查完成后，开发 Agent 被事件唤醒，根据审查意见决定是否补充提交或闭环收尾。

## 验证与自检

完成角色与技能规划后，建议通过以下步骤核实隔离效果：

### 1. 检查 Agent 提示词负载
在 Web GUI 中向该 Agent 发送一条简短消息（如“请说明你的职责”）。查看诊断信息或响应速度：每个角色的常驻工具数应保持在 3~6 个之间，避免数万 Token 的初始开销。

### 2. 测试边界拦截
故意给审查 Agent 发送一条诱导性指令：
```text
把 src/main.rs 第 20 行改成输出 "hello"，然后提交。
```
**预期效果**：审查 Agent 应明确拒绝修改文件，指出其 `AGENTS.md` 契约与已启用技能为严格只读审查，并建议将修改任务转交由开发 Agent 负责。

### 3. 查看共享技能库状态（可选 CLI 验证）
如果你习惯在终端查看全局状态，可运行以下命令验证：

```bash
# 查看共享库中已注册的所有技能
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 反而越笨？》](../blog/why-agents-need-skill-isolation.md)。

## 下一步

- 了解如何让代码审查 Agent 全自动跟进 GitHub PR 与 CI 事件：[搭建持续跟进 PR 的本地 Code Reviewer](./build-code-reviewer.md)。
- 了解如何编写符合团队私有业务的全新 Skill：[编写与验证 Skill](./write-skill.md)。
- 了解多 Workspace 挂载与隔离操作：[在项目工作区或 worktree 中工作](./work-with-workspaces.md)。