企业官网建设流程全解析

OpenRig AgentSpec 详解：agent.yaml 里 skills、guidance、hooks 与 profiles 完整指南

【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig是一个多智能体运行框架（Multi-agent Harness），能把 Claude Code 和 Codex 当作同一个系统里的不同成员来编排。而AgentSpec（核心载体就是每个智能体目录下的agent.yaml）正是 OpenRig 智能体的"简历 + 岗位说明书"：它声明这个 Agent 是谁、用什么运行时、携带哪些技能（skills）、读哪份角色指引（guidance）、挂载哪些钩子（hooks），以及通过什么画像（profiles）装配成最终上岗的样子。

一、AgentSpec 长什么样：一个最小真实示例

先看仓库里最精简的示例——demo 的 lead 智能体 agent.yaml 只有 7 行：

name: lead version: "1.0.0" resources: skills: [] profiles: default: uses: skills: []

再看一个"满配"的生产级示例：内置的 implementer 智能体 agent.yaml，它几乎展示了 AgentSpec 的全部字段。我们把整份文件拆成 6 个板块来读：

下面逐一拆解四个核心概念。

二、skills：给智能体装配"技能包"

skills是 AgentSpec 中最像"能力"的部分。每个 skill 是一个目录 + 一份SKILL.md，描述一项可被模型调用的工作方法。

内置的公共技能库 shared/agent.yaml 中登记了十几项技能，例如：

• test-driven-development—— 测试驱动开发，先写测试再写实现（SKILL.md）
• systematic-debugging—— 系统化排错
• verification-before-completion—— 完成前先验证
• development-team/orchestration-team/review-team—— 面向不同团队协作场景的流程技能

在 implementer 的agent.yaml里，这些技能被写入profiles.default.uses.skills，意味着该智能体上岗后就"会"这些方法。你可以理解为：skills 决定 Agent 会做什么，而不只是它是谁。技能目录整体可参考 skills/_canonical/，技能加载逻辑的源码在 skill-loadout-surface.ts。

三、guidance：用一份 Markdown 定义角色

guidance是纯文本的角色指引文件。implementer 声明了：

resources: guidance: - id: role path: guidance/role.md

对应的 role.md 用几段话写清了角色契约：从哪个任务地址出发、如何按"最小一致修复"原则改代码、如何返回证据与不确定性。

skills 和 guidance 的分工很清晰：

• guidance= 这个角色的"工作守则"，告诉模型如何思考
• skills= 工具箱里的"具体方法"，告诉模型有哪些招式可用

而且startup.files会把role.md在会话启动时直接投递给模型（delivery_hint: send_text），保证角色说明第一时间进入上下文。

四、hooks：通过 runtime_resources 挂载钩子

OpenRig 里的"钩子"并不写进 YAML 主流程，而是通过runtime_resources声明，随运行时（Claude Code 或 Codex）一起注入。在 shared 库中可以看到四件套：

其中claude-activity-hooks就是最典型的 hooks：它把 Claude 的执行活动（读文件、跑命令、完成步骤）回传给 OpenRig 守护进程，让 TUI 的拓扑图、健康检测和注意力面板能看到"每个 Agent 干到哪一步了"。相关实现可见 claude-activity-hook-up-route.test.ts。

一句话：hooks 让框架"看得见"智能体，这是多 Agent 系统可观测性的基础。

五、profiles：一个 Agent，多种上岗形态

profiles（画像）是 AgentSpec 的装配层。resources只是"仓库里有什么"，而profiles.xxx.uses才决定"这次用哪些"。

profiles: default: uses: skills: [development-team, test-driven-development, systematic-debugging, verification-before-completion] guidance: [] plugins: [shared:openrig-core] runtime_resources: [shared:claude-default-settings, shared:claude-activity-hooks, ...]

这意味着你可以为同一个智能体定义多个画像（比如default和strict），在 rig.yaml 里用profile: default一行切换。demo 的 rig.yaml 就是这种用法：6 个成员都引用profile: default，但运行时分属claude-code和codex两套引擎——这正是 OpenRig "两种引擎、一个系统"的体现。

六、从 agent.yaml 到整机拓扑：验证你的 AgentSpec

AgentSpec 不是孤岛——rig.yaml把多个 AgentSpec 通过agent_ref: "local:agents/lead"之类的引用装进 pod（小组），再用edges声明协作关系（如delegates_to、can_observe）。启动后，你可以：

1. 运行 demo：参考 demo/README.md 执行demo/run.sh
2. 在 UI 的 Explorer 里点击demorig，查看它由 AgentSpec 装配出的实时拓扑
3. 观察每个节点的运行状态（百分比、运行时图标：蓝点为 Claude、绿点为 Codex）

七、速查清单：编写 agent.yaml 的 5 步

✅1. 定身份：name、version、description✅2. 选运行时：defaults.runtime设为claude-code或codex✅3. 配资源：在resources中登记 skills、guidance 与 runtime_resources（含 hooks） ✅4. 写画像：在profiles里通过uses勾选实际要装配的资源 ✅5. 加启动动作：用startup.files/startup.actions保证角色指引先于任务到达

掌握 skills、guidance、hooks 与 profiles 这四个概念，你就读懂了 OpenRig AgentSpec 的全部骨架：技能给方法，指引给角色，钩子给视野，画像给装配。从 demo/agents/ 的 7 行起步，再到 packages/daemon/specs/agents/ 的满配范式，按需扩展即可。

【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig