技能使用指南

maintain-cross-platform（维护跨平台架构）Skill 是什么？如何保障三平台兼容发布？

维护跨平台架构Skill 是面向仓库维护者的元技能，帮你一次性对齐 Claude Code、OpenCode、Codex CLI 三大平台的命令、代理、技能与配置，内置 6 个验证器与三阶段预推送钩子，覆盖 11 个版本字段对齐、硬编码路径检查、文档计数校验与 RC／生产发布流程，让跨平台发布不再靠人工记忆。想快速上手？读完本篇即可照着跑通全流程。

维护跨平台架构Skillmaintain-cross-platform
21 个章节 约 22 分钟阅读 AI 智能生成

维护跨平台架构Skill：一次维护，让 Claude Code、OpenCode、Codex CLI 三平台齐步走

  • 一句话定位：这是一个面向仓库维护者的「元技能」，专门用来维护 AgentSys 在 Claude Code、OpenCode、Codex CLI 三个平台上的架构一致性，覆盖发布准备、兼容性验证与安装基础设施更新。
  • 核心机制：把三平台差异整理成完整对照表，把「容易忘、容易错」的环节交给 6 个验证器 + 预推送钩子自动拦截。
  • 关键规则：三个平台必须都能工作，没有例外；所有版本字段必须在 11 个文件里保持一致。
  • 产出可预期：按固定输出格式生成「跨平台兼容性检查」报告，问题定位到文件:行。
  • 适用边界：这是范围限定在本仓库的本地技能（scope: local），受众是 repo-maintainers，不是给普通终端用户的操作类工具。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 维护跨平台架构Skill
技能英文名 maintain-cross-platform
技能ID 13134
技能类型 元技能（metadata 中标注为「元技能：维护三平台架构」）
作用范围 本地技能（scope: local）
目标受众 仓库维护者（repo-maintainers）

它到底解决什么问题

AgentSys 同时要支持 Claude Code、OpenCode、Codex CLI 三个平台，而这三个平台在配置格式、目录位置、命令前缀、Frontmatter 写法上全都不一样：Claude Code 用 JSON 配置、/ 前缀，OpenCode 用 JSON/JSONC 与 .opencode/ 状态目录，Codex CLI 用 TOML 配置、$ 前缀，还要求技能描述里写清「触发短语」。

结果是同一个功能，要在三套结构里分别落地，还要保持版本号、文档计数、安装脚本三者不打架。最常见的事故不是「功能写不出来」，而是「改了 A 平台，忘了 B 平台」「版本号只在 package.json 里改了」「代理里硬编码了 .claude/ 路径导致另外两个平台直接崩」。这个技能就是把这些隐性知识固化成一套可执行的检查清单。

一键安装思路与步骤

需要先说明：该技能不是独立发布的命令行工具，它随 AgentSys 仓库分发，定位是「本仓库的本地技能」。因此安装的本质是——让技能文件出现在你所用平台的技能目录里，并且能被助手发现调用。以下为基于技能详情给出的真实路径与入口。

安装前提

  1. 你拥有 AgentSys 仓库的维护权限（这是给仓库维护者用的技能）。
  2. 本机具备 Node.js / npm 环境，因为校验与测试依赖 npm run validate、npm test、npm pack --dry-run。
  3. 你已经决定要在哪几个平台上工作（可以多选三平台中的任意组合）。

安装步骤

  1. 确认技能文件位置：按仓库约定，技能以 plugins/*/skills/*/SKILL.md 的形式存在，该技能的 SKILL.md 需放在对应插件的 skills/ 目录下，frontmatter 中包含 name、description、metadata。
  2. Claude Code 平台：通过插件市场方式安装，详情给出的入口为添加市场 claude plugin marketplace add agent-sh/agentsys，再用 claude plugin install {plugin}@agentsys 安装对应插件；技能由插件捆绑提供，无需单独复制。
  3. OpenCode 平台：技能目录为 .opencode/skills/（注意是单数形式），命令与代理会被安装程序复制到 ~/.config/opencode/commands/ 与 ~/.config/opencode/agents/，配置文件为 ~/.config/opencode/opencode.json。
  4. Codex CLI 平台：技能目录为 ~/.codex/skills/，由安装程序的技能映射创建 SKILL.md，配置写入 ~/.codex/config.toml；注意 Codex 对技能描述有硬性要求，必须包含「当用户询问……时使用」这类触发短语。
  5. 装好后跑一次验证：执行 npm run validate，它串联运行 6 个验证器；再执行 npm test（1400+ 测试）。若全部通过，说明三平台的基础结构没有被破坏。

如何验证技能真的生效

  • 直接向助手提出「准备发布、验证跨平台兼容性」这类请求，观察它是否按技能规定输出「跨平台兼容性检查」报告结构（包含运行的验证、发现的问题、此技能中的不对齐、自动化机会、采取的行动、下一步）。
  • 观察报告中的问题是否带「文件:行」级别的定位，而不是笼统地说「大概有问题」。

具体的安装入口、版本号与发布渠道以官方说明为准；技能详情未提供价格信息，是否收费同样以官方说明为准。

该技能的主要功能和特点

  • 三平台差异完整矩阵：一次性给出配置格式（JSON / JSON/JSONC / TOML）、配置位置（~/.claude/settings.json、~/.config/opencode/opencode.json、~/.codex/config.toml）、状态目录（.claude/、.opencode/、.codex/）、命令前缀（/、/、$）、项目说明文件（CLAUDE.md、AGENTS.md、AGENTS.md）的对照关系，不用再翻三方文档。
  • 组件级位置映射：命令、代理、技能、钩子在每个平台分别该放哪里，写得清清楚楚。例如代理在 Claude Code 放在插件 agents/，OpenCode 放在 ~/.config/opencode/agents/，Codex 则不支持代理、改用 MCP 工具承接逻辑。
  • Frontmatter 转换规则：把 tools: Bash(git:*) 转成 permission: { bash: "allow" } 这类映射直接列成表；还解释了 --strip-models 标志为什么存在——为没有三档模型权限的 OpenCode 用户移除模型声明，改用用户默认模型。
  • 平台适配细节提示：${CLAUDE_PLUGIN_ROOT} 需替换为 ${PLUGIN_ROOT}；require() 里的 Windows 反斜杠需要规范化，否则字符串转义会把路径打断。这些是踩过一次就丢半天的坑。
  • 六件套验证套件：validate-plugins（插件结构与 plugin.json 有效性）、validate-cross-platform（三平台兼容）、validate-consistency（仓库完整性）、validate-paths（禁止硬编码 .claude/ 等路径）、validate-counts（文档计数与版本对齐）、validate-platform-docs（平台文档一致性）。
  • 发布流程模板化：RC 版本（3.X.0-rc.N）与生产版本（3.X.0）各自的操作步骤固定为「更新版本 → 更新 CHANGELOG → 验证 → 提交打标签 → 确认发布」，并给出快速版本自检命令。
  • 预推送钩子三阶段：阶段一跑完整验证套件；阶段二检测到代理/技能/钩子/提示词被修改时，追问「是否已运行 /enhance」；阶段三若推送的是版本标签，则额外跑测试与打包检查。
  • 常见陷阱清单：忘记同步插件版本、硬编码 .claude/ 路径、代理计数不一致、Codex 技能缺触发短语、OpenCode 标签超长（建议截断到 30 字符以内）、忘记运行 /enhance，六大高频翻车点逐一配了「症状 + 谁抓住它」。
  • 自带进化机制：关键规则第 5 条明确要求——发现不对齐或新的自动化机会，就更新这个技能文件本身。这让它不会随仓库演进而腐化。

和「凭记忆维护多平台」相比，它强的地方在于：把散落在发布流程、安装脚本、CI 配置里的隐性规则，变成可以阅读、可以执行、可以被验证器强制的显性知识。

如何使用该技能？

第一步：明确触发时机

技能描述已经限定了三个使用场景：准备发布、验证跨平台兼容性、更新安装基础设施。只要落在这三类里，就应当先调用它，而不是直接动手改文件。

第二步：先跑基线验证

npm run validate

这一步会跑完 6 个验证器。先拿到「改之前是什么状态」，才能判断后面出的问题是不是你引入的。

第三步：按矩阵逐项核对改动

例如你要新增一个命令，技能给出的清单是：

  1. 在 plugins/my-plugin/commands/my-command.md 创建命令文件；
  2. 更新 bin/cli.js 的三处：PLUGINS_ARRAY（新插件时）、OPENCODE_COMMAND_MAPPINGS、CODEX_SKILL_MAPPINGS；
  3. 更新 .claude-plugin/marketplace.json 的插件数组；
  4. 创建 plugins/my-plugin/.claude-plugin/plugin.json；
  5. 更新 docs/INSTALLATION.md、README.md、CHANGELOG.md；
  6. 再跑 npm run validate，让验证器捕获缺失的映射。

映射的写法也有固定格式，可以直接照抄：

// OpenCode 命令映射
['my-command.md', 'my-plugin', 'my-command.md']

// Codex 技能映射（第四项是触发短语）
['my-command', 'my-plugin', 'my-command.md', '当用户询问"触发短语"时使用。能力描述。']

第四步：执行发布流程

以 RC 为例，技能给出的五步是：

  1. 把 11 个文件的版本字段统一提升到目标版本（package.json、根 plugin.json、marketplace.json、mcp-server/index.js 中的 MCP_SERVER_VERSION，以及 9 个插件的 plugin.json）；
  2. 在 CHANGELOG.md 顶部按「新增 / 变更 / 修复」添加条目；
  3. 依次运行 npm run validate、npm test、npm pack --dry-run；
  4. 提交并打标签：git commit -m "chore: release v3.6.0-rc.1"、git tag v3.6.0-rc.1、git push origin main --tags；
  5. 等 GitHub Actions 跑完后用 npm view agentsys@rc version 确认线上版本。

生产发布与 RC 的差别只有两点：去掉 -rc.N 后缀，标签改用无后缀的 v3.X.0，npm 会自动发到 latest 通道。

第五步：按固定格式产出报告

技能规定了输出骨架，照着填即可：

## 跨平台兼容性检查

### 运行的验证
- [OK] validate:plugins
- [ERROR] validate:paths

### 发现的问题
- agents/my-agent.md:42 发现硬编码 .claude/ 路径

### 此技能中的不对齐
- 新增脚本未在「验证套件」章节记录

### 自动化机会
- 版本号提升可脚本化，建议 scripts/bump-version.js

### 采取的行动
- 修改 agents/my-agent.md，改用 AI_STATE_DIR

### 下一步
- 重新运行 npm run validate 确认通过

这种固定结构的好处是：评审时一眼能看出「哪些验证过了、哪些没过、谁在什么时候改了什么」，不会出现「口头说跑过了但没人复核」的情况。

第六步：回写技能本身

如果这次发现新的平台差异、新的验证需求，或者某个手动步骤明显可以自动化，按技能自身的要求，把它补充进对应章节（平台差异矩阵、常见陷阱、验证套件、潜在改进），并提交一条 docs(maintain-cross-platform): ... 类型的提交。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
maintain-cross-platform（本技能） 仓库内元技能，维护三平台架构一致性 平台差异矩阵、组件位置映射、Frontmatter 转换规则、6 个验证器说明、发布流程、陷阱清单、固定输出报告 需具备仓库维护权限与 Node.js 环境；技能文件需落入对应平台技能目录 多平台插件仓库的发布准备、兼容性验证、安装基础设施更新 优势：规则显性化、可被验证器强制执行、自带更新机制；不足：范围严格限定在本仓库，不能直接迁移到其他项目
纯人工维护 + 代码评审 靠维护者记忆与评审经验兜底 人工比对三平台文件、人工改版本号、人工检查文档 无需安装，但极度依赖个人经验 平台少、迭代慢的小型项目 优势：零成本启动；不足：版本对齐、路径硬编码、计数不一致等问题全靠人眼，极易漏检，且知识无法沉淀
单平台插件脚手架（仅 Claude Code 模板） 面向单一平台的插件初始化模板 生成插件目录结构、plugin.json、命令与代理骨架 门槛低，按模板填空即可 只做 Claude Code 一个平台的场景 优势：上手快、结构规范；不足：完全没有覆盖 OpenCode 与 Codex 的目录、前缀、Frontmatter 差异，跨平台时等于从零开始
自建 CI 校验脚本 自行编写 shell / Node 脚本做检查 自定义路径检查、版本号比对、文档计数校验 门槛高，需要自己设计检查规则并长期维护 有一定工程积累、愿意自研工具的团队 优势：完全贴合自身需求；不足：规则设计与维护成本高，缺少平台差异知识库，脚本本身也容易腐化

从对比可以看出，这个技能真正的差异点不在「检查」本身，而在检查什么、为什么检查——它把三平台差异知识、验证器语义、发布流程与历史陷阱打包成一份可执行文档，这是通用脚手架和自研脚本都不具备的部分。

该技能的典型应用场景与实际体验情况

场景一：版本发布前的封版检查（仓库维护者）

痛点：一次 RC 发布要动 11 个版本字段，散落在 package.json、根插件清单、市场清单、MCP 服务器常量与 9 个插件清单里。靠手工搜索替换，漏改一个就会导致「本地显示 3.6.0，插件市场显示 3.5.0」的尴尬局面。

使用方式：按技能给出的发布五步走，改完后跑 npm run validate:counts，让验证器直接告诉你「版本不对齐」。

实际体验：这一步的收益最直观。技能把「11 个文件」这个容易被忽略的数量直接写在关键规则里，配合验证器，基本消灭了版本漂移类事故。注意点是：验证器只验证一致性，不替你改文件，版本提升目前仍是手动或半自动过程，技能自身也把「版本提升自动化」列为潜在改进项。

场景二：新增命令或代理时的三平台同步（功能开发者）

痛点：在 Claude Code 里写好的命令，到了 OpenCode 要转 Frontmatter（工具声明变权限声明、移除模型字段），到了 Codex 干脆要变成带触发短语的技能。开发者不熟悉这些转换，往往只改一个平台就提了 PR。

使用方式：对照技能里的「添加新功能（逐步）」章节，逐个勾选需要改的位置，包括 bin/cli.js 里的三处映射。

实际体验：上手难度中等偏高，第一次需要花时间理解「命令 → 技能」这条转换链路。但一旦照着做过一遍，后续新增功能的动作就标准化了。注意事项：OpenCode 的标签长度有隐含限制，技能提到需截断到 30 字符以内，否则会直接抛错，这一条在文档里很容易被忽略，属于典型的「不看就踩坑」。

场景三：排查跨平台特有的诡异故障（排障者）

痛点：功能在 Claude Code 上一切正常，到 OpenCode 就找不到文件——原因是代理里硬编码了 .claude/ 路径。这类问题用常规单元测试很难覆盖，因为测试环境恰好就是这个平台。

使用方式：跑 npm run validate:paths，它会用正则扫描 .claude/、.opencode/、.codex/ 的硬编码模式，并明确跳过文档表格、平台对比示例、技能文档等安全上下文。

实际体验：这是技能里「智能化程度」最高的部分之一。它对安全上下文的排除规则写得比较细，避免误报刷屏，实际使用中噪音很低。注意事项：正因为有排除规则，如果问题恰好写在被跳过的上下文里，需要人工复核，不能完全依赖脚本结论。

场景四：文档与代码同步走查（文档维护者）

痛点：仓库里有 9 个插件、39 个代理（29 个基于文件 + 10 个基于角色）、23 个技能，README、CLAUDE.md、AGENTS.md 里到处写着这些数字。新增一个代理忘了改文档，读者看到的计数就是错的。

使用方式：npm run validate:counts 会比对插件数、代理数、技能数、版本对齐情况，还会检查 CLAUDE.md 与 AGENTS.md 的关键规则相似度是否高于 90%。

实际体验：验证器「智能验证」的设计比较贴心——它接受「39 代理」或「39 代理（29 基于文件 + 10 基于角色）」两种写法，也会跳过插件内部的局部计数，只校验顶级总数，因此不会因为写法差异频繁报错。注意事项：计数基于文件系统实际扫描，所以新增目录后必须先落盘再验证。

该技能能为用户带来的价值

把「靠记忆」变成「靠流程」。跨平台维护最大的成本不是写代码，而是记住三个平台在配置、目录、前缀、Frontmatter 上的所有差异。技能把这些差异固化在矩阵里，新加入的维护者不必再从零摸索。

把「事后救火」提前为「推送前拦截」。预推送钩子在三个阶段分别拦截：验证不过不许推、改了增强内容没跑 /enhance 不许推、发版本标签但测试或打包失败不许推。问题发现得越早，修复成本越低。

把「隐性知识」变成「可审计的证据」。固定输出格式让每次检查都有据可查：哪几个验证器跑过、报了什么错、定位到哪一行、下一步做什么。评审时不再依赖「我觉得应该没问题」。

降低多人协作的沟通成本。当版本字段、文档计数、平台文档一致性都由验证器兜底后，代码评审可以聚焦在真正的逻辑问题上，而不是反复追问「OpenCode 那边改了吗」。

长期价值在于自我更新。技能明确要求：发现不对齐、发现新的平台差异、发现可自动化的手动步骤，就回写进这个文件。这意味着它的价值会随仓库演进而累积，而不是像一次性文档那样快速过时。技能中还列了 5 个潜在自动化方向（版本提升、CHANGELOG 生成、跨平台安装冒烟测试、文档计数自动更新、市场清单同步），为后续优化留了明确的路标。

边界与代价也要说清楚：它是本地技能、只服务本仓库，不具备通用性；它会要求你在推送前多跑几条命令，短期内看是「增加了步骤」，但相比发布后回滚，这个成本几乎可以忽略。

常见问题 FAQ

Q1：这个技能怎么安装？必须三个平台都装吗？

不必须。它随 AgentSys 仓库分发，属于本地技能，安装的本质是让 SKILL.md 出现在你所用平台的技能目录：Claude Code 通过插件市场由插件捆绑提供，OpenCode 使用 .opencode/skills/（单数）目录，Codex CLI 使用 ~/.codex/skills/ 目录并需要触发短语描述。你可以只装自己实际使用的平台。但要注意，关键规则第 1 条写得很明确——三个平台必须都能工作，无例外，这说的是仓库的兼容性要求，不是要求你本机必须装三套环境。具体命令以官方说明为准。

Q2：这个技能收费吗？

技能详情中没有提供任何价格信息，是否收费、如何授权请以官方说明为准。可以确定的是，它的定位是仓库维护工具，本身不具备独立的商业授权形态。

Q3：它适合谁用？普通用户需要装吗？

只适合仓库维护者（metadata 里 audience 写的就是 repo-maintainers）。如果你只是想用 AgentSys 的功能写代码，完全不需要它；如果你要发版本、改安装脚本、加命令或代理、排查跨平台故障，它才有价值。scope 标注为 local，也说明它是绑定在本仓库上的。

Q4：和直接用验证脚本或自建 CI 比，优势在哪？

验证脚本只回答「有没有问题」，这个技能还回答「为什么会有问题、该怎么改、改完还要注意什么」。它包含平台差异矩阵、Frontmatter 转换规则、六类常见陷阱、发布五步流程，这些是脚本无法承载的知识层内容；同时它又把脚本组织成可执行的 6 个验证器和三阶段预推送钩子，避免只停留在文档层面。自建 CI 更灵活，但规则设计和长期维护成本都更高。

Q5：我改了技能里没写的新平台差异，该怎么办？

按技能的关键规则第 5 条，这正是它期望你做的事：把新差异补进「平台差异」矩阵，如果是会导致问题的差异，再补进「常见陷阱」，必要时扩展验证脚本并在「验证套件」章节登记，最后提交一条 docs(maintain-cross-platform): 记录 xxx 类型的提交。技能不是死文档，它把「更新自己」写成了使用者的责任之一。