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/openrigOpenRig是一个多智能体运行框架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 个板块来读字段作用一句话理解name/version/description身份标识给 Agent 起名、定版本、写简介defaults默认运行时不指定时默认跑claude-codeimports复用公共资源引入shared里的技能库、插件与钩子resources资源清单声明 skills、guidance、插件、runtime_resourcesprofiles装配方案决定哪个画像用到哪些资源startup启动动作会话启动时投递文件、执行动作下面逐一拆解四个核心概念。二、skills给智能体装配技能包skills是 AgentSpec 中最像能力的部分。每个 skill 是一个目录 一份SKILL.md描述一项可被模型调用的工作方法。内置的公共技能库 shared/agent.yaml 中登记了十几项技能例如test-driven-development—— 测试驱动开发先写测试再写实现SKILL.mdsystematic-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 库中可以看到四件套资源 ID类型用途claude-default-settingsclaude_settings_fragmentClaude 默认设置片段claude-default-mcpclaude_mcp_fragmentMCP 服务器配置片段codex-default-configcodex_config_fragmentCodex 默认配置片段claude-activity-hooksclaude_activity_hooks活动钩子采集 Agent 行为信号其中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 到整机拓扑验证你的 AgentSpecAgentSpec 不是孤岛——rig.yaml把多个 AgentSpec 通过agent_ref: local:agents/lead之类的引用装进 pod小组再用edges声明协作关系如delegates_to、can_observe。启动后你可以运行 demo参考 demo/README.md 执行demo/run.sh在 UI 的 Explorer 里点击demorig查看它由 AgentSpec 装配出的实时拓扑观察每个节点的运行状态百分比、运行时图标蓝点为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考