Agent 角色系统与多工具链适配

Agent 角色系统与多工具链适配

学习目标

• 理解三个专业角色的设计视角和输出格式
• 掌握 Claude Code 子 Agent 自动发现机制
• 学会应用 Persona Frontmatter 的支持字段和不支持字段
• 理解多工具链适配的文件组织策略

前置知识

本章涉及多 Agent 路由与隔离的通用原理，建议先阅读：

• 多 Agent 路由与隔离
• Skill 渐进式知识管理

下文直接聚焦 agent-skills 的具体实现。

项目实践

三个专业角色的设计

Persona	角色	视角	最佳适用
code-reviewer	Senior Staff Engineer	五轴审查（正确性、可读性、架构、安全、性能）	合并前的代码审查
security-auditor	Security Engineer	漏洞检测、威胁建模、OWASP 审计	安全敏感代码审查
test-engineer	QA Engineer	测试策略、覆盖率分析、Prove-It 模式	测试缺失分析

每个角色是单个视角，产生单个输出格式。如果发现需要添加第二个角色，创建第二个 Persona 文件，而不是在现有文件中增加。

Claude Code 子 Agent 自动发现

agent-skills 作为 Claude Code 插件，其 agents/ 目录下的 Persona 文件被自动发现：

• 不需要路径配置——插件根目录的 agents/ 被自动扫描
• 使用 Agent 工具时指定 subagent_type: code-reviewer 即可调用
• /ship 命令是经典的并行扇出示例：在单个 assistant turn 中多次调用 Agent 工具

Agent Teams 实验性功能：需要设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 环境变量。Persona 文件无需修改即可作为 Agent Teams 角色使用——区别在于 spawning 方式不同（subagent 报告结果，teammate 可以互相消息）。

Persona Frontmatter 支持字段

支持的字段：name、description、tools、disallowedTools、model、maxTurns、skills、memory、background、effort、isolation、color、initialPrompt

不支持的字段（静默忽略）：hooks、mcpServers、permissionMode

成本优化建议：按 Persona 设置不同的模型——test-engineer 用 Haiku（覆盖率扫描），code-reviewer 用 Sonnet，security-auditor 用 Opus。

多工具链适配策略

agent-skills 通过 7 种方式适配不同的编码工具：

工具	适配方式	安装命令
Claude Code	插件目录（推荐）	/plugin marketplace add
Cursor	复制到 .cursor/rules/	见 docs/cursor-setup.md
Gemini CLI	原生技能安装	gemini skills install
Windsurf	添加到规则配置	见 docs/windsurf-setup.md
OpenCode	skill 工具 + 意图映射	见 docs/opencode-setup.md
GitHub Copilot	使用 agents/ 作为角色	见 docs/copilot-setup.md
Codex / 其他	纯 Markdown 直接读取	见 docs/getting-started.md

OpenCode 的特殊适配：OpenCode 不支持斜杠命令，而是通过 AGENTS.md 中的意图映射和 skill 工具实现技能驱动执行：

# AGENTS.md 中的意图映射
Feature / new functionality → spec-driven-development, incremental-implementation
Bug / failure → debugging-and-error-recovery
Code review → code-review-and-quality

问题与规避

陷阱	表现	对策
在 Persona 中添加 hooks	静默忽略，行为不一致	将 hooks 移到项目设置中配置
角色职责重叠	两个角色产生相同类型的发现	拆分视角，每个角色专注一个维度
模型选择不当	Haiku 做安全审计，漏掉深层问题	按角色复杂度选择模型
Agent Teams 与 Subagent 混淆	用 Subagent 期望队友互发消息	Subagent 只报告结果，Teams 队友可互发消息

设计取舍

为什么只有三个角色？

角色数量不是越多越好。三个角色覆盖了代码审查的三个关键维度：质量、安全、测试。增加更多角色会增加编排复杂度，但边际收益递减。agent-skills 的设计哲学是”少而精的角色，通过技能组合扩展能力”。

为什么支持 7+ 种工具链？

AI 编码工具市场碎片化，每种工具都有自己的指令加载机制。通过提供适配指南而非强制单一工具，agent-skills 确保了最大的兼容性。纯 Markdown 的格式是这种兼容性的基础——任何能读取 Markdown 的 AI Agent 都可以使用这些技能。

参考来源

• 源码验证: agents/README.md — 角色关系和决策矩阵
• 源码验证: CLAUDE.md — 插件约定和项目结构
• 源码验证: AGENTS.md — OpenCode 适配的意图映射