oh-my-openagent shared-skills 包深度解析跨 Harness 的 SKILL.md 技能分发管线与 DMCA-safe 第三方内容物化机制【免费下载链接】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导读packages/shared-skills是 oh-my-openagentOmO中由人工编写、在 OpenCode 与 Codex 两个 Harness执行环境之间共享的技能SKILL.md捆绑包OpenCode 运行时直接以字面拷贝加载而 Codex 侧通过sync-skills.mjs这一唯一的转换器完成适配。本篇文章以 packages/shared-skills/AGENTS.md 为骨架结合仓库源码与测试完整讲解该包的目录布局、17 个技能的构成与单个技能的目录规范、从skills/源码到两个运行时消费端的整条流水线以及仓库如何通过子模块 构建期物化的 DMCA-safe 模型合规地引入前端第三方参考资料。读完本文你将掌握这套技能包的定位、分发拓扑、测试纪律与可复用的前端资源物化方案。一、包定位人工编写的跨 Harness 技能捆绑包1.1 一句话定位shared-skills是由人手工编写hand-authored、在 OpenCode 与 Codex 两个版本之间共享的技能包包内主要是技能数据本身仅在技能确需自持脚本/资源时附带scripts/并且包内不做任何转换no transform inside the package——转换发生在下游的 Codex 插件构建链中。从 packages/shared-skills/package.json 可以看到它的发布形态{ name: oh-my-opencode/shared-skills, version: 0.1.0, type: module, private: true, description: Cross-harness SKILL.md files shared between OMO and Codex, exports: { .: { types: ./index.d.ts, import: ./index.mjs }, ./skill-source-filter: { types: ./skill-source-filter.d.ts, import: ./skill-source-filter.mjs } }, files: [ index.d.ts, index.mjs, skills, skill-source-filter.d.ts, skill-source-filter.mjs ] }files字段明确限定了 npm 包的内容入口类型声明、入口实现、整个skills/目录以及一个被 omo-codex 与 omo-senpi 的同步脚本共同消费的skill-source-filter模块。1.2 根路径探测sharedSkillsRootPath()包的核心导出是sharedSkillsRootPath()返回skills/目录的绝对路径。它的实现位于 packages/shared-skills/index.mjs核心思路是就近优先探测// Bundlers inline this module, so import.meta.url points at the consuming bundle, and the // distance to the skills directory depends on where that bundle landed: // dist/index.js - dist/skills (sibling) // dist/cli/index.js - dist/skills (parent) // dist/cli-node/index.js - dist/skills (parent) // plugins/omo/dist/cli/ - plugins/omo/skills (grandparent; the Codex marketplace layout) const SKILLS_PROBE_SPECIFIERS [./skills/, ../skills/, ../../skills/]; export function sharedSkillsRootPath() { const candidates SKILLS_PROBE_SPECIFIERS.map((specifier) fileURLToPath(new URL(specifier, import.meta.url)), ); return candidates.find((candidate) existsSync(candidate)) ?? candidates[0]; }之所以需要三级探测是因为打包器会把该模块内联进消费方 bundle此时import.meta.url指向的是 bundle 所在位置而 bundle 落点与skills/目录的距离取决于打包布局dist/index.js→dist/skills同级siblingdist/cli/index.js与dist/cli-node/index.js→dist/skills父级parentCodex marketplace 布局plugins/omo/dist/cli/→plugins/omo/skills祖父级grandparent。探测按最近优先执行命中的即返回没有任何候选命中时回退到 sibling 路径保持原有的 not-found 行为不变。对应的类型声明只有一行export function sharedSkillsRootPath(): string见 packages/shared-skills/index.d.ts。二、技能清单与目录规范2.1 17 个共享技能skills/name/下共有 17 个技能见 skills/ 目录programming、debugging、frontend、visual-qa、ast-grep、coding-agent-sessions、data-scientist、git-master、refactor、review-work、ulw-execute、ulw-plan、ulw-research、init-deep、remove-ai-slops、lsp-setup、ultimate-browsing。其中ultimate-browsing是唯一携带真正子项目的技能skills/ultimate-browsing/engine/是一个 17 模块的 Python 包自带 CLI、配置 schema 与测试套件。它是对fivetaku/insane-search的刻意固定版本deliberately pinned、本地分叉locally diverged快照而不是跟随上游 HEAD 的镜像。在改动或重新 vendor 之前必须先阅读 engine 的 AGENTS.md §UPSTREAM BASELINE AND VERSION POLICY。另有三只 Codex 专属技能lcx-report-bug、lcx-contribute-bug-fix、lcx-doctor已迁出本包改由 packages/omo-codex/plugin/components/lcx/skills/ 维护——它们的lcx-前缀即表示Codex-only无 OpenCode 对应物。2.2 单个技能的目录规范每个技能的布局约定为SKILL.mdYAML frontmatter 含name:与带触发词triggers的单行description:它是路由/索引router/index。references/可选真正的正文内容所在SKILL.md负责指向它们scripts/可选技能自持的脚本或资产agents/openai.yaml可选3 个技能带有 Codex 的 agent 角色声明。以 ast-grep 技能 为典型样例frontmatter 中name: ast-grepdescription是一条带触发语义的单行文本Searches and rewrites code by AST shape across 25 languages...正文以路由式结构展开——何时使用、三条必须内化的原则、scripts/ast_grep_helper.py辅助脚本用法、直接使用sg的 CLI 速查、决策树、只读必读清单references/patterns.md、references/pitfalls.md、references/recipes.md、references/cli.md、references/yaml-rules.md、references/sgconfig.md、references/install.md以及不可破坏的不变量validate before searching、dry-run before applying、two-pass writes、单引号包裹$VAR等。需要强调frontmatter 中没有location:字段这与.agents/skills/下的技能不同这是本包技能的统一约定。三、分发流水线一个字面拷贝一个唯一转换器skills/ (source) ├─ build:shared-skills-assets (root) → cp -R skills dist/skills # literal copy, no transform ├─ skills-loader-core → loadSkillsFromDir(sharedSkillsRootPath(), scope:shared) # OpenCode runtime └─ omo-codex/plugin/scripts/sync-skills.mjs → plugin/skills/ # the only transformer 1. copies 10 omo-codex COMPONENT skills FIRST (comment-checker, lcx-*, lsp, rules, teammode, ulw-loop, ulw-plan, ultrawork from plugin/components/*/skills/*); same-named shared skills are skipped → ulw-plan/ultrawork in Codex come from components, NOT from here 2. copies remaining shared skills 3. adaptSkillForCodex(): inserts Codex Harness Tool Compatibility sections; overlays ulw-execute/review-work; writes agents/openai.yaml display metadata with the (OmO) prefix; filters out tests, caches, and source metadata → ships to ~/.codex/.../skills/3.1 OpenCode 侧字面拷贝 运行时加载根级构建任务build:shared-skills-assets对skills/做cp -R的字面拷贝不做任何转换。OpenCode 运行时通过skills-loader-core以workspace:*依赖本包调用loadSkillsFromDir(sharedSkillsRootPath(), scope: shared)加载。也就是说OpenCode 消费的是与源码逐字节一致的技能。3.2 Codex 侧sync-skills.mjs是唯一转换器Codex 消费端位于omo-codex/plugin/scripts/sync-skills.mjs它按三步执行先拷贝 10 个 omo-codex 组件技能comment-checker、lcx-*、lsp、rules、teammode、ulw-loop、ulw-plan、ultrawork来源为plugin/components/*/skills/*遇到同名共享技能时跳过——因此 Codex 侧的ulw-plan/ultrawork来自组件而非本包ulw-plan由人工双维护本包与packages/omo-codex/plugin/components/ultrawork/skills/ulw-plan/各一份需保持同步再拷贝剩余的共享技能调用adaptSkillForCodex()插入 Codex Harness Tool Compatibility 章节、对ulw-execute/review-work做 overlay、写入带(OmO) 前缀展示元数据的agents/openai.yaml并过滤掉测试、缓存与源码元数据最终投递到~/.codex/.../skills/。3.3 拷贝过滤规则的机器化skill-source-filter过滤掉测试与缓存并非在sync-skills.mjs里随意硬编码而是下沉为一个独立模块 packages/shared-skills/skill-source-filter.mjs并被 omo-codex 与 omo-senpi 两侧的 sync 脚本共同消费。它导出一个fs.cp兼容的过滤函数createSkillSourceCopyFilter(sourceRoot, options)其关键设计是export const ignoredSkillSourceDirNames Object.freeze([.mypy_cache, .omo, .pytest_cache, .ruff_cache, __pycache__]); export const ignoredSkillSourceFileNames Object.freeze([.gitignore, .npmignore, pyrightconfig.json]); const sourceTestFilePattern /\.test\.ts$/;过滤段基于相对拷贝根目录的路径段判断而不是绝对路径——这是因为技能树可能被检出在~/.omo/...下或位于某个名字里带__pycache__的祖先目录之下若按绝对路径测试会错误地拒绝掉本应正常打包的技能。被忽略的内容包括缓存目录.mypy_cache、.pytest_cache、.ruff_cache、__pycache__、.omo、配置文件.gitignore、.npmignore、pyrightconfig.json、*.test.ts与*.pyc以及scripts/tests目录。四、frontend 技能的第三方引用DMCA-safe 的子模块 构建期物化模型这是本包最具工程价值的部分。frontend技能的 brand / taste-skill / ui-ux-db / designpowers 四类引用内容属于第三方内容仓库在 DMCA-safe 模型下采取零提交副本 构建期物化策略。4.1 模型总览upstreams/{open-design,taste-skill,ui-ux-pro-max,designpowers} # pinned submodules (provenance, build input) └─ packages/shared-skills/scripts/frontend-refs-manifest.mjs # single source of truth: partition upstream path map └─ packages/shared-skills/scripts/materialize-frontend-refs.mjs # path-mapped copy SKILL.md description quoting └─ chokepoint: packages/omo-codex/plugin/scripts/materialize-shared-upstreams.mjs • PREPENDED to the codex plugin build chain BEFORE sync-skills.mjs (every ship path runs it) • root build:shared-skills-assets root prepack also run it每个上游是upstreams/name下的固定版本pinnedgit 子模块提供溯源provenance并作为构建输入它们不在skills/下因此永远不会进入 tarball构建时把引用文件按路径映射path-mapped物化进skills/frontend/references/{design,ui-ux-db,designpowers/vendor}文件正文逐字节拷贝唯一的例外是物化后的SKILL.mdfrontmatter 可能把未加引号的单行description:标量规范化为 JSON 引号包裹的 YAML 字符串以保证 Codex/OpenCode 的 frontmatter 解析确定性description 文本本身不变。4.2 单一事实来源frontend-refs-manifest.mjspackages/shared-skills/scripts/frontend-refs-manifest.mjs 是分区与上游路径映射的单一事实来源。它定义了designOriginals12 个项目原创设计文档README.md、_INDEX.md、ambience-skill.md、aside.md、clone-from-url.md、design-system-architecture.md、interaction-skill.md、layout-skill.md、lazyweb.md、print-paged-media.md、react-dev-tooling-skill.md、stylegallery.md这些保持提交brandStems约 68 个品牌airbnb、apple、figma、linear.app、notion、opencode.ai、stripe、vercel……每个品牌对应design-systems/brand/DESIGN.md的open-design上游文件映射到references/design/brand.mdtasteSkillFiles与tasteSkillArtifactFiles12 个 taste-skill 文件taste-skill.md、gpt-tasteskill.md、minimalist-skill.md、brutalist-skill.md、soft-skill.md、redesign-skill.md、image-to-code-skill.md、output-skill.md、stitch-skill.md、imagegen-frontend-web.md、imagegen-frontend-mobile.md、imagegen-brandkit.md加上stitch-design-example.md→stitch-skill/DESIGN.mduiUxDbFileRenames、uiUxDbStackFilesastro、flutter、nextjs、react、shadcn、vue 等 13 个技术栈 CSV、uiUxDbDataFilescharts、colors、icons、landing、products、typography、ux-guidelines 等 11 类数据 CSV与uiUxDbScriptscore.py、design_system.py、search.py统一从ui-ux-pro-max上游映射。designMaterializeMap()、uiUxDbMaterializeMap()与designpowersMaterializeMap()最终合并为thirdPartyMaterializeMap()即一次构建要物化的完整文件清单。4.3 物化实现materialize-frontend-refs.mjspackages/shared-skills/scripts/materialize-frontend-refs.mjs 提供materializeFrontendRefs({ strict })先检查四个上游子模块是否已初始化目录存在且除.git外有内容未初始化时strict: false则告警并跳过return { materialized: 0, skipped: true }strict: true则抛错并给出补救命令git submodule update --init packages/shared-skills/upstreams/name清空references/ui-ux-db与references/designpowers/vendor后遍历映射逐文件写盘materializedContent()只对SKILL.md目标以及 designpowers vendor 中来源是SKILL.md的reference.md做normalizeSkillFrontmatter()——即把description: 未加引号单行标量重写为description: JSON.stringify(...)的引号形式其余文件逐字节原样拷贝。关键工程点物化产物是 GITIGNORED 的skills/frontend/.gitignore因此永远不会被提交进仓库但skills/frontend/.npmignore会覆盖该.gitignore使 npm pack 时物化后的引用照常随包发布。lazycodex marketplace 同步是原始文件拷贝因此发布的是插件构建物化后磁盘上的内容。4.4 溯源与 CI 守卫ATTRIBUTION每次物化在产物中钉住上游 SHAPinned upstream commit:script/update-frontend-upstreams.mjs 负责升级子模块并重写 pin--check校验 pin 与子模块 HEAD 一致无需联网provenance-gate.test.ts若任一第三方路径被提交、物化集合缺失、或 pin 漂移CI 直接失败materialize-frontend-refs.test.ts覆盖允许的SKILL.mddescription 引号规范化子模块初始化的容错策略仅在 script/agent/setup.sh 中非致命离线开发者得到一棵缺失 brand 引用的工作树而插件构建链以--strict运行CI/发布必然产出完整包。五、消费者与测试纪律5.1 消费者清单skills-loader-coreworkspace:*——内置/共享技能加载的默认skillsRootPathpackages/omo-opencode/src/cli/install-ast-grep-sg.ts对应仓库路径为packages/omo-opencode/src/cli/install-ast-grep-sg.ts——为二进制安装定位 ast-grep 技能目录omo-codex/pluginfile:依赖——sync-skills.mjs是唯一转换器。5.2 打包由测试钉死打包形态由 packages/omo-opencode/src/shared-skills-package.test.ts 钉死校验 workspace 包含关系、files条目以及每个技能都能被解析。5.3 内容与测试的边界只测机器消费的东西本包最明确的测试纪律是技能正文是散文PROSE不要用测试去钉死措辞。技能正文是模型要读的指令用toContain断言一句话、用not.toContain断言旧措辞消失、或统计词数/字符数守卫的是 diff 而非行为并且会阻塞每一次合理编辑参见.omo/rules/test-discipline.md§PROMPT TESTS。只允许对机器消费的部分设置守卫打包shared-skills-package.test.ts个人令牌擦除depersonalization-gate.test.ts——安全排除项第三方清单frontend-thirdparty-manifest.test.ts根路径探测shared-skills-root-path.test.tsupstreams.test.tsstylegallery 路由成员资格frontend-stylegallery-routing.test.tsultimate-browsing 运行时固定ultimate-browsing-runtime-pins.test.ts。纯散文的技能修改在评审通过后不需要新增测试——原本位于本包的那些散文固定契约测试已被移除因为它们属于假装覆盖pretend-coverage。六、实战要点速查找技能根路径调用sharedSkillsRootPath()按./skills/→../skills/→../../skills/就近探测覆盖dist/index.jssibling、dist/cli/index.jsparent与 Codex marketplace 布局plugins/omo/dist/cli/grandparent三种落点。改技能内容直接编辑skills/name/SKILL.md与其references/OpenCode 侧构建为字面cp -RCodex 侧由sync-skills.mjs适配插 Tool Compatibility 章节、写(OmO)前缀元数据、过滤测试/缓存/源元数据。改ulw-plan记住它是人工双维护——本包与omo-codex/plugin/components/ultrawork/skills/ulw-plan/各一份sync-skills.mjs不会把共享版本拷给 Codex。升级 frontend 上游用script/update-frontend-upstreams.mjs提升子模块并重写Pinned upstream commit:--check离线校验不要手工提交任何第三方文件否则provenance-gate.test.ts会在 CI 拦截。离线开发script/agent/setup.sh中子模块初始化非致命可得到缺少 brand 引用的工作树但任何发布路径都会以--strict要求完整物化。七、小结packages/shared-skills用最朴素的方式解决了跨 Harness 技能复用源码即最终形态OpenCode外加唯一转换点Codex 的sync-skills.mjs。它的工程精髓在于三个分离——技能内容与构建转换分离、机器消费面与模型阅读面分离测试纪律、第三方内容与仓库本体分离子模块 构建期物化 CI 溯源门禁。这套零提交副本、构建期物化、pin 溯源的 DMCA-safe 模型以及路径段相对过滤的拷贝规则都可以直接迁移到其他需要分发带第三方依赖的技能/提示词资产的工程中。【免费下载链接】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），仅供参考