oh-my-openagent 项目级 Skills 与 Slash Commands 迁移指南.agents/目录的设计、加载机制与维护规范【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent导读本文围绕 oh-my-openagentOmO仓库根目录下的.agents/目录展开它是项目级 skills 与 slash commands 的新一代归属地在oh-my-opencode→oh-my-openagent更名过渡期该目录是旧.opencode/布局的迁移目标并作为其严格超集承载了 14 个 skills 与 5 个斜杠命令。读完本文你将掌握.agents/与.opencode/的共存关系、skill 被加载器发现与按作用域去重的底层机制、5 个命令与 5 个 NEW skills 的双触发方式以及迁移期间必须遵守的目录维护规范如 drift-sync、npm 排除守卫并能在自己的仓库中正确落地这套项目级技能组织方案。一、背景为什么需要.agents/这个新目录.agents/目录是 oh-my-openagent 项目在改名过渡期引入的“项目级技能与命令”新布局。旧版项目名oh-my-opencode使用.opencode/目录存放同类内容而在更名之后.agents/成为这些内容的迁移目标migration target.opencode/则被标记为 legacy 布局。两者的关系可以用三点概括严格超集.agents/是.opencode/的严格超集skills 数量 5 → 14同时包含 5 个命令凡是.opencode/有的.agents/都有并行加载在迁移窗口期内两个目录会被同时加载由 opencode-skill-loader 统一负责按作用域去重当两个目录声明了同名的 skill 或命令时加载器按作用域优先级裁决更高优先级的作用域胜出。从 skills-loader-core 的加载器实现 可以看到discoverAllSkills会一次性并行发现 7 类来源opencode 项目技能、opencode 全局技能、共享技能packages/shared-skills、Claude 项目技能、Claude 用户技能、.agents项目技能与.agents全局技能最后统一按名称去重合并。.agents/正是在这条发现管线中的一等公民。二、SKILLS14 个项目级技能清单.agents/skills/下共 14 个技能其中 5 个与.opencode/共享同一份指令其余为.agents/独有。下表是原文档给出的完整清单Skill是否也在.opencode/用途work-with-pr/yes完整 PR 生命周期work-with-pr-workspace/yes迭代工作区 benchmark 输入github-triage/yes只读 issue/PR 分流产出证据报告hyperplan/yes对抗式多智能体规划pre-publish-review/yes12 智能体发布前检查门禁get-unpublished-changes/NEW/get-unpublished-changes命令的 skill 形态omomomo/NEW/omomomo彩蛋的 skill 形态publish/NEW/publish命令的 skill 形态remove-deadcode/NEW/remove-deadcode命令的 skill 形态security-research/NEW团队模式安全审计3 名漏洞猎人 2 名 PoC 工程师codex-qa/no隔离式 Codex Light QA真实codex app-server 隔离CODEX_HOME 本地 mock 模型hook 触发断言辅助脚本均自带--self-testopencode-qa/noopencode CLI/TUI/事件流 QA通过 SSE 的 hook 触发断言、会话数据库检查、tmux TUI 冒烟测试辅助脚本均自带--self-testsenpi-qa/no针对真实senpi二进制的 Senpi 适配器 task-engine QA隔离在独立SENPI_CODING_AGENT_DIR中scripts/resolve-evidence-dir.mjs将所有产物钉在.omo/evidence/omo-senpi-adapter/slug/下tech-debt-audit/no基于 AST-grep/grep 的 9 维度技术债审计产出TECH_DEBT_AUDIT.md2.1 五种 NEW 技能命令与技能的「双触发」设计其中 5 个标记为 NEW 的技能get-unpublished-changes、omomomo、publish、remove-deadcode、security-research是命令的技能化等价物——它们与.opencode/command/和.agents/command/中的同名斜杠命令内容等价但允许同一份指令以两种方式被触发显式/command调用匹配提示词时由技能自动加载skill auto-loading。以security-research为例其 SKILL.md 的 frontmatter 中声明了完整的触发词集合security-research、security review、vulnerability audit等含韩文等价词因此既可通过/security-research命令唤起也会在用户自然语言命中这些触发词时自动加载。该技能要求team_*工具可用否则会明确提示用户启用team_mode.enabled: true并重启 opencode——这是“命令与技能共用同一套硬前置条件”的典型示例。而codex-qa、opencode-qa、senpi-qa、tech-debt-audit四个技能是.agents/独有的没有对应的命令形态只能通过技能自动加载触发。2.2 三个 QA 技能隔离与证据纪律三个 QA 类技能codex-qa、opencode-qa、senpi-qa共享一套严格的隔离原则绝不触碰用户的真实环境codex-qa强制使用隔离的CODEX_HOME 本地 mock 模型绝不调用真实模型 API也绝不读写用户真实的~/.codex并且每次运行都会对~/.codex/config.toml做 shasum 前后比对以证明真实主目录未被改动见 codex-qa/SKILL.md证据即产物所有 QA 的捕获 JSON / 终端面板必须写入.omo/evidence/YYYYMMDD-slug/没有证据文件等于 QA 未发生senpi-qa则由 resolve-evidence-dir.mjs 统一将产物定位到.omo/evidence/omo-senpi-adapter/slug/脚本自带回归每个辅助脚本都提供--self-test脚本既是 QA 工具又是自身的回归检查。2.3 tech-debt-audit9 维度技术债审计协议tech-debt-audit/SKILL.md 定义了一套模型无关的审计协议使用 OMO 内置工具grep、glob、bashsg、read、lsp_diagnostics、task在 9 个维度上逐项扫描并强制每条发现带file:line:col引用Architectural Decay架构腐化sg模块依赖图找循环、god class、TODO|FIXME|HACK标记密度Consistency Rot一致性腐化多种 HTTP 客户端、直接console.*、类型逃逸as any/ts-ignoreType Contract Debt类型与契约债any类型、ts-expect-error压制、lsp_diagnostics类型错误Test Debt测试债关键路径零测试、test.skip、慢测试Dependency Config Debt依赖与配置债npm audit已知 CVE、重复职责依赖、硬编码密钥Performance Resource Hygiene性能与资源卫生循环内await、顺序 async 迭代、事件监听器泄漏Error Handling Observability错误处理与可观测性空 catch 块、被吞掉的 promise 错误链Security Hygiene安全卫生硬编码密钥、字符串拼接 SQL、innerHTML/eval注入向量Documentation Drift文档漂移README 声称与实际不符、注释与代码矛盾。审计最终产出带严重度分级Critical/High/Medium/Low与工时估算的TECH_DEBT_AUDIT.md超过 5 万行的大型代码库可并行派发 2~3 个后台子代理task(..., run_in_backgroundtrue)分担最重的维度。注意该协议刻意要求输出 “Looks Bad But Is Fine” 章节记录“看似是债、实为有意设计”的模式避免误报。三、COMMANDS5 个斜杠命令.agents/command/下是 5 个斜杠命令与.opencode/command/的集合完全一致/get-unpublished-changes/omomomo/publish/remove-deadcode/security-research以 get-unpublished-changes.md 为例可以看到这些命令文档的实际形态它包含命令指令强制立即输出分析、禁止照抄 commit message、必须读 diff 描述真实变化、版本上下文通过npm view/node -p/git tag注入已发布版本、本地版本与最新 tag、git 上下文git log v{version}..HEAD与git diff --stat、输出格式模板feat/fix/refactor/docs 分组、Layered Impact Matrix、分层的版本号建议以及按需触发的 Oracle 部署安全审查段落触发词为 “safe to deploy” 等先跑bun run typecheckbun test失败则直接判定不可部署。命令文档的核心特征是把真实可执行的 shell 命令内嵌为version-context/git-context块由 CLI 执行后把结果注入模板。命令文档还内置了发布分层模型这是 oh-my-openagent 多包发布流程的关键概念层范围版本问题omo pure componentspackages/*-core、MCP 包、packages/shared-skills、可复用脚本即使适配器仅内部消费共享组件是否也需要 patch/minor/major 发布说明omo opencode根oh-my-opencode/oh-my-openagent、src/、.opencode/、.agents/、CLI、配置、hooks、工具、文档OpenCode/OpenAgent npm 包该用哪个 semver 增量omo codexpackages/omo-codex、lazycodex-ai、Codex 插件元数据/hooks、捆绑的 MCP 运行时、marketplace 载荷LazyCodex 需要同版本号、独立说明还是 marketplace 发布同时命令会排除匹配senpi、omo-senpi、senpi-task、pi-goal、pi-webfetch的提交与路径仅在内部适配器排除台账中记录。四、加载机制skill 如何被发现、解析与去重.agents/之所以能成为项目级技能的一等公民底层依赖的是 skills-loader-core 中的一条完整管线omo-opencode侧的 loader.ts 与 index.ts 均为对它的 re-export。4.1 目录发现向上递归查找在 project-discovery-dirs.ts 中.agents/skills与.claude/skills、.opencode/skills含.opencode/skill兼容路径并列findProjectAgentsSkillDirs从当前工作目录开始逐级向上查找.agents/skills目录并以git rev-parse --show-toplevel探测到的仓库根作为终止边界支持 git worktree且带 5 秒超时与路径缓存。这解释了为什么项目任意子目录中启动 opencode 都能加载到仓库根部的.agents/skills。4.2 技能解析frontmatter 与模板包装在 loaded-skill-from-path.ts 中每个技能目录下的SKILL.md或与目录同名的.md会经历frontmatter 解析读取name、description、model、agent、subtask、argument-hint、license、compatibility、allowed-tools、mcp等元数据MCP 配置解析优先读取技能目录下的mcp.json其次解析 frontmatter 内嵌的 mcp 配置路径引用解析正文中的path文件引用会基于技能目录相对解析再被包装成带Base directory for this skill: 目录/头注的skill-instruction模板模型字段清洗model经过sanitizeModelField处理opencode 来源与 claude-code 来源使用不同的清洗上下文描述加作用域前缀description 被格式化为(scope - Skill) 原描述便于在工具列表中区分来源。4.3 去重与作用域优先级同名技能的去重分为两层同一来源内的去重加载时按名称用 Map 收敛见 skill-directory-loader.ts同名技能只保留先加载者跨来源的最终去重所有来源合并后再次按名称去重skill-deduplication.ts。关键点在于合并顺序本身即优先级顺序。观察 discoverAllSkills 的拼接顺序opencode 项目 → opencode 全局 → Claude 项目 →.agents项目 → Claude 用户 →.agents全局 → 共享技能后出现者覆盖先出现者。这与 scope-priority.ts 定义的数值优先级builtin/shared: 1 config: 2 user: 3 opencode: 4 project: 5 opencode-project: 6互相印证——项目级作用域project优先于用户级user与全局级opencode。因此当.opencode/与.agents/声明同名技能时后者更高优先级作用域获胜这正是原文档所述 “the higher-priority scope wins” 的源码依据。五、迁移状态与共存策略.agents/与.opencode/并非永久并存而是过渡期设计。原文档的迁移计划可概括为一张决策表关注点计划为什么有两个目录.opencode/是旧布局.agents/是更名后面向未来的名称.opencode/何时移除多 harness 重构落地且现有用户完成重装之后跟踪见 ROADMAP两个目录存在冲突技能怎么办加载器按名称去重高优先级作用域胜出当前 5 个共享技能work-with-pr、hyperplan等在两目录间字节级一致若出现分歧先修.agents/一侧新技能放哪里只放.agents/禁止向.opencode/添加新条目仓库中还留有过渡期运行时状态的直接证据background-tasks.json 与.opencode/background-tasks.json并行存在记录后台子代理任务的会话归属与运行状态是“双目录过渡”在运行时层面的具体体现。六、维护规范与反模式Conventions Anti-patterns为了确保过渡期不失控原文档明确规定了三条纪律6.1 规范Conventions所有新技能一律进入.agents/.opencode/冻结除 5 个共享技能的 drift-sync 外不做任何新增共享技能的漂移即 bug更新任一共享技能时必须在同一个提交内同步更新两处副本直到.opencode/被移除斜杠命令保持双份过渡窗口期内两个目录必须包含相同的command/*.md集合。6.2 反模式Anti-patterns绝不向.opencode/添加.agents/中不存在的技能绝不允许 5 个共享技能漂移——CI 最终应强制字节级相等在此之前靠人工自觉绝不在多 harness 重构落地前删除.opencode/。6.3 npm 排除守卫skills/.npmignore原文档特别指出一个 Bun 生态的坑在 Bun 1.3.x 下对于package.json#files中列出的目录根级.npmignore不生效。因此.agents/skills/.npmignore作为与发布内容同目录的守卫专门排除仅内部使用的资产__*、.private/、.draft/前缀/目录并且由 package-layout-exclusion.test.ts 强制校验该守卫始终存在。这保证了内部材料不会意外流入 npm 发布包同时把“排除策略”与“被排除内容”放在同一目录降低维护者遗漏的风险。七、实操如何在你的仓库落地这套方案基于.agents/的既有实践项目级技能体系的最小落地路径如下建目录在仓库根创建.agents/skills/skill-name/SKILL.md技能与.agents/command/cmd-name.md命令写 frontmatter每个SKILL.md至少声明name与descriptiondescription 中写清用途与触发词让技能在自然语言匹配时能被自动加载触发词设计参考security-research、codex-qa的写法把命令别名、英文/本地化关键词一并放入 description扩大自动加载命中面命令文档内嵌可执行上下文仿照get-unpublished-changes.md用!前缀命令块注入版本、git 等实时上下文让命令输出始终基于最新仓库状态遵守去重规则牢记“高优先级作用域胜出”——项目级会覆盖用户级与全局级同名技能利用这一点做项目定制覆盖依赖既有测试基线修改技能加载相关代码时可参考 opencode-skill-loader 目录 下的loader.test.ts、merger.test.ts、loaded-skill-from-path.test.ts、skill-deduplication相关测试以及agents-skills-global.test.ts这些测试共同锁定了.agents/发现、解析、去重的行为契约。八、总结.agents/目录是 oh-my-openagent 在更名过渡期对“项目级技能与命令”的一次布局升级它既是.opencode/的严格超集又通过 opencode-skill-loader 的按作用域去重机制实现了与新老目录的平滑共存。14 个技能中既有覆盖 PR 全流程、多智能体规划、发布门禁等研发主线的通用能力也有codex-qa/opencode-qa/senpi-qa这类强调隔离与证据纪律的专项 QA 技能以及 9 维度技术债审计协议5 个斜杠命令则与同名技能互为“命令/技能”双形态。对仓库维护者而言真正重要的是遵守“新技能只进.agents/、共享技能同提交同步、命令保持双份”的三条纪律直到多 harness 重构落地、.opencode/正式退役。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-openagent 项目级 Skills 与 Slash Commands 迁移指南：`.agents/` 目录的设计、加载机制与维护规范
oh-my-openagent 项目级 Skills 与 Slash Commands 迁移指南.agents/目录的设计、加载机制与维护规范【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent导读本文围绕 oh-my-openagentOmO仓库根目录下的.agents/目录展开它是项目级 skills 与 slash commands 的新一代归属地在oh-my-opencode→oh-my-openagent更名过渡期该目录是旧.opencode/布局的迁移目标并作为其严格超集承载了 14 个 skills 与 5 个斜杠命令。读完本文你将掌握.agents/与.opencode/的共存关系、skill 被加载器发现与按作用域去重的底层机制、5 个命令与 5 个 NEW skills 的双触发方式以及迁移期间必须遵守的目录维护规范如 drift-sync、npm 排除守卫并能在自己的仓库中正确落地这套项目级技能组织方案。一、背景为什么需要.agents/这个新目录.agents/目录是 oh-my-openagent 项目在改名过渡期引入的“项目级技能与命令”新布局。旧版项目名oh-my-opencode使用.opencode/目录存放同类内容而在更名之后.agents/成为这些内容的迁移目标migration target.opencode/则被标记为 legacy 布局。两者的关系可以用三点概括严格超集.agents/是.opencode/的严格超集skills 数量 5 → 14同时包含 5 个命令凡是.opencode/有的.agents/都有并行加载在迁移窗口期内两个目录会被同时加载由 opencode-skill-loader 统一负责按作用域去重当两个目录声明了同名的 skill 或命令时加载器按作用域优先级裁决更高优先级的作用域胜出。从 skills-loader-core 的加载器实现 可以看到discoverAllSkills会一次性并行发现 7 类来源opencode 项目技能、opencode 全局技能、共享技能packages/shared-skills、Claude 项目技能、Claude 用户技能、.agents项目技能与.agents全局技能最后统一按名称去重合并。.agents/正是在这条发现管线中的一等公民。二、SKILLS14 个项目级技能清单.agents/skills/下共 14 个技能其中 5 个与.opencode/共享同一份指令其余为.agents/独有。下表是原文档给出的完整清单Skill是否也在.opencode/用途work-with-pr/yes完整 PR 生命周期work-with-pr-workspace/yes迭代工作区 benchmark 输入github-triage/yes只读 issue/PR 分流产出证据报告hyperplan/yes对抗式多智能体规划pre-publish-review/yes12 智能体发布前检查门禁get-unpublished-changes/NEW/get-unpublished-changes命令的 skill 形态omomomo/NEW/omomomo彩蛋的 skill 形态publish/NEW/publish命令的 skill 形态remove-deadcode/NEW/remove-deadcode命令的 skill 形态security-research/NEW团队模式安全审计3 名漏洞猎人 2 名 PoC 工程师codex-qa/no隔离式 Codex Light QA真实codex app-server 隔离CODEX_HOME 本地 mock 模型hook 触发断言辅助脚本均自带--self-testopencode-qa/noopencode CLI/TUI/事件流 QA通过 SSE 的 hook 触发断言、会话数据库检查、tmux TUI 冒烟测试辅助脚本均自带--self-testsenpi-qa/no针对真实senpi二进制的 Senpi 适配器 task-engine QA隔离在独立SENPI_CODING_AGENT_DIR中scripts/resolve-evidence-dir.mjs将所有产物钉在.omo/evidence/omo-senpi-adapter/slug/下tech-debt-audit/no基于 AST-grep/grep 的 9 维度技术债审计产出TECH_DEBT_AUDIT.md2.1 五种 NEW 技能命令与技能的「双触发」设计其中 5 个标记为 NEW 的技能get-unpublished-changes、omomomo、publish、remove-deadcode、security-research是命令的技能化等价物——它们与.opencode/command/和.agents/command/中的同名斜杠命令内容等价但允许同一份指令以两种方式被触发显式/command调用匹配提示词时由技能自动加载skill auto-loading。以security-research为例其 SKILL.md 的 frontmatter 中声明了完整的触发词集合security-research、security review、vulnerability audit等含韩文等价词因此既可通过/security-research命令唤起也会在用户自然语言命中这些触发词时自动加载。该技能要求team_*工具可用否则会明确提示用户启用team_mode.enabled: true并重启 opencode——这是“命令与技能共用同一套硬前置条件”的典型示例。而codex-qa、opencode-qa、senpi-qa、tech-debt-audit四个技能是.agents/独有的没有对应的命令形态只能通过技能自动加载触发。2.2 三个 QA 技能隔离与证据纪律三个 QA 类技能codex-qa、opencode-qa、senpi-qa共享一套严格的隔离原则绝不触碰用户的真实环境codex-qa强制使用隔离的CODEX_HOME 本地 mock 模型绝不调用真实模型 API也绝不读写用户真实的~/.codex并且每次运行都会对~/.codex/config.toml做 shasum 前后比对以证明真实主目录未被改动见 codex-qa/SKILL.md证据即产物所有 QA 的捕获 JSON / 终端面板必须写入.omo/evidence/YYYYMMDD-slug/没有证据文件等于 QA 未发生senpi-qa则由 resolve-evidence-dir.mjs 统一将产物定位到.omo/evidence/omo-senpi-adapter/slug/脚本自带回归每个辅助脚本都提供--self-test脚本既是 QA 工具又是自身的回归检查。2.3 tech-debt-audit9 维度技术债审计协议tech-debt-audit/SKILL.md 定义了一套模型无关的审计协议使用 OMO 内置工具grep、glob、bashsg、read、lsp_diagnostics、task在 9 个维度上逐项扫描并强制每条发现带file:line:col引用Architectural Decay架构腐化sg模块依赖图找循环、god class、TODO|FIXME|HACK标记密度Consistency Rot一致性腐化多种 HTTP 客户端、直接console.*、类型逃逸as any/ts-ignoreType Contract Debt类型与契约债any类型、ts-expect-error压制、lsp_diagnostics类型错误Test Debt测试债关键路径零测试、test.skip、慢测试Dependency Config Debt依赖与配置债npm audit已知 CVE、重复职责依赖、硬编码密钥Performance Resource Hygiene性能与资源卫生循环内await、顺序 async 迭代、事件监听器泄漏Error Handling Observability错误处理与可观测性空 catch 块、被吞掉的 promise 错误链Security Hygiene安全卫生硬编码密钥、字符串拼接 SQL、innerHTML/eval注入向量Documentation Drift文档漂移README 声称与实际不符、注释与代码矛盾。审计最终产出带严重度分级Critical/High/Medium/Low与工时估算的TECH_DEBT_AUDIT.md超过 5 万行的大型代码库可并行派发 2~3 个后台子代理task(..., run_in_backgroundtrue)分担最重的维度。注意该协议刻意要求输出 “Looks Bad But Is Fine” 章节记录“看似是债、实为有意设计”的模式避免误报。三、COMMANDS5 个斜杠命令.agents/command/下是 5 个斜杠命令与.opencode/command/的集合完全一致/get-unpublished-changes/omomomo/publish/remove-deadcode/security-research以 get-unpublished-changes.md 为例可以看到这些命令文档的实际形态它包含命令指令强制立即输出分析、禁止照抄 commit message、必须读 diff 描述真实变化、版本上下文通过npm view/node -p/git tag注入已发布版本、本地版本与最新 tag、git 上下文git log v{version}..HEAD与git diff --stat、输出格式模板feat/fix/refactor/docs 分组、Layered Impact Matrix、分层的版本号建议以及按需触发的 Oracle 部署安全审查段落触发词为 “safe to deploy” 等先跑bun run typecheckbun test失败则直接判定不可部署。命令文档的核心特征是把真实可执行的 shell 命令内嵌为version-context/git-context块由 CLI 执行后把结果注入模板。命令文档还内置了发布分层模型这是 oh-my-openagent 多包发布流程的关键概念层范围版本问题omo pure componentspackages/*-core、MCP 包、packages/shared-skills、可复用脚本即使适配器仅内部消费共享组件是否也需要 patch/minor/major 发布说明omo opencode根oh-my-opencode/oh-my-openagent、src/、.opencode/、.agents/、CLI、配置、hooks、工具、文档OpenCode/OpenAgent npm 包该用哪个 semver 增量omo codexpackages/omo-codex、lazycodex-ai、Codex 插件元数据/hooks、捆绑的 MCP 运行时、marketplace 载荷LazyCodex 需要同版本号、独立说明还是 marketplace 发布同时命令会排除匹配senpi、omo-senpi、senpi-task、pi-goal、pi-webfetch的提交与路径仅在内部适配器排除台账中记录。四、加载机制skill 如何被发现、解析与去重.agents/之所以能成为项目级技能的一等公民底层依赖的是 skills-loader-core 中的一条完整管线omo-opencode侧的 loader.ts 与 index.ts 均为对它的 re-export。4.1 目录发现向上递归查找在 project-discovery-dirs.ts 中.agents/skills与.claude/skills、.opencode/skills含.opencode/skill兼容路径并列findProjectAgentsSkillDirs从当前工作目录开始逐级向上查找.agents/skills目录并以git rev-parse --show-toplevel探测到的仓库根作为终止边界支持 git worktree且带 5 秒超时与路径缓存。这解释了为什么项目任意子目录中启动 opencode 都能加载到仓库根部的.agents/skills。4.2 技能解析frontmatter 与模板包装在 loaded-skill-from-path.ts 中每个技能目录下的SKILL.md或与目录同名的.md会经历frontmatter 解析读取name、description、model、agent、subtask、argument-hint、license、compatibility、allowed-tools、mcp等元数据MCP 配置解析优先读取技能目录下的mcp.json其次解析 frontmatter 内嵌的 mcp 配置路径引用解析正文中的path文件引用会基于技能目录相对解析再被包装成带Base directory for this skill: 目录/头注的skill-instruction模板模型字段清洗model经过sanitizeModelField处理opencode 来源与 claude-code 来源使用不同的清洗上下文描述加作用域前缀description 被格式化为(scope - Skill) 原描述便于在工具列表中区分来源。4.3 去重与作用域优先级同名技能的去重分为两层同一来源内的去重加载时按名称用 Map 收敛见 skill-directory-loader.ts同名技能只保留先加载者跨来源的最终去重所有来源合并后再次按名称去重skill-deduplication.ts。关键点在于合并顺序本身即优先级顺序。观察 discoverAllSkills 的拼接顺序opencode 项目 → opencode 全局 → Claude 项目 →.agents项目 → Claude 用户 →.agents全局 → 共享技能后出现者覆盖先出现者。这与 scope-priority.ts 定义的数值优先级builtin/shared: 1 config: 2 user: 3 opencode: 4 project: 5 opencode-project: 6互相印证——项目级作用域project优先于用户级user与全局级opencode。因此当.opencode/与.agents/声明同名技能时后者更高优先级作用域获胜这正是原文档所述 “the higher-priority scope wins” 的源码依据。五、迁移状态与共存策略.agents/与.opencode/并非永久并存而是过渡期设计。原文档的迁移计划可概括为一张决策表关注点计划为什么有两个目录.opencode/是旧布局.agents/是更名后面向未来的名称.opencode/何时移除多 harness 重构落地且现有用户完成重装之后跟踪见 ROADMAP两个目录存在冲突技能怎么办加载器按名称去重高优先级作用域胜出当前 5 个共享技能work-with-pr、hyperplan等在两目录间字节级一致若出现分歧先修.agents/一侧新技能放哪里只放.agents/禁止向.opencode/添加新条目仓库中还留有过渡期运行时状态的直接证据background-tasks.json 与.opencode/background-tasks.json并行存在记录后台子代理任务的会话归属与运行状态是“双目录过渡”在运行时层面的具体体现。六、维护规范与反模式Conventions Anti-patterns为了确保过渡期不失控原文档明确规定了三条纪律6.1 规范Conventions所有新技能一律进入.agents/.opencode/冻结除 5 个共享技能的 drift-sync 外不做任何新增共享技能的漂移即 bug更新任一共享技能时必须在同一个提交内同步更新两处副本直到.opencode/被移除斜杠命令保持双份过渡窗口期内两个目录必须包含相同的command/*.md集合。6.2 反模式Anti-patterns绝不向.opencode/添加.agents/中不存在的技能绝不允许 5 个共享技能漂移——CI 最终应强制字节级相等在此之前靠人工自觉绝不在多 harness 重构落地前删除.opencode/。6.3 npm 排除守卫skills/.npmignore原文档特别指出一个 Bun 生态的坑在 Bun 1.3.x 下对于package.json#files中列出的目录根级.npmignore不生效。因此.agents/skills/.npmignore作为与发布内容同目录的守卫专门排除仅内部使用的资产__*、.private/、.draft/前缀/目录并且由 package-layout-exclusion.test.ts 强制校验该守卫始终存在。这保证了内部材料不会意外流入 npm 发布包同时把“排除策略”与“被排除内容”放在同一目录降低维护者遗漏的风险。七、实操如何在你的仓库落地这套方案基于.agents/的既有实践项目级技能体系的最小落地路径如下建目录在仓库根创建.agents/skills/skill-name/SKILL.md技能与.agents/command/cmd-name.md命令写 frontmatter每个SKILL.md至少声明name与descriptiondescription 中写清用途与触发词让技能在自然语言匹配时能被自动加载触发词设计参考security-research、codex-qa的写法把命令别名、英文/本地化关键词一并放入 description扩大自动加载命中面命令文档内嵌可执行上下文仿照get-unpublished-changes.md用!前缀命令块注入版本、git 等实时上下文让命令输出始终基于最新仓库状态遵守去重规则牢记“高优先级作用域胜出”——项目级会覆盖用户级与全局级同名技能利用这一点做项目定制覆盖依赖既有测试基线修改技能加载相关代码时可参考 opencode-skill-loader 目录 下的loader.test.ts、merger.test.ts、loaded-skill-from-path.test.ts、skill-deduplication相关测试以及agents-skills-global.test.ts这些测试共同锁定了.agents/发现、解析、去重的行为契约。八、总结.agents/目录是 oh-my-openagent 在更名过渡期对“项目级技能与命令”的一次布局升级它既是.opencode/的严格超集又通过 opencode-skill-loader 的按作用域去重机制实现了与新老目录的平滑共存。14 个技能中既有覆盖 PR 全流程、多智能体规划、发布门禁等研发主线的通用能力也有codex-qa/opencode-qa/senpi-qa这类强调隔离与证据纪律的专项 QA 技能以及 9 维度技术债审计协议5 个斜杠命令则与同名技能互为“命令/技能”双形态。对仓库维护者而言真正重要的是遵守“新技能只进.agents/、共享技能同提交同步、命令保持双份”的三条纪律直到多 harness 重构落地、.opencode/正式退役。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考