Skillporter 检查跨编程代理的技能迁移差异
Skillporter 是开发中的开源 CLI,用于转换代理技能并生成迁移差异报告。文章指出,复制 SKILL.md 及附件并不能保证行为一致,还需检查发现路径、元数据、权限、钩子和命令依赖。
AI 深度解读
把一个带有 SKILL.md 的目录从 Claude Code 复制到 Codex CLI,文件能完整到达,技能却未必按原来的方式工作。权限字段是否生效、命令占位符是否展开、脚本是否依赖原来的宿主,都可能在迁移后发生变化。
Skillporter 想解决的就是这个落差:转换技能时,同时报告哪些内容保留了、哪些能力降级了、哪些地方还无法确认。它值得关注的地方,是把「文件搬过去了」和「行为兼容了」分开检查。不过,作者提供的验证规模还很小,工具目前也只是实验性公开 alpha。
为什么 SKILL.md 没变,行为仍然可能变
SKILL.md 是共同入口,却不是完整的行为协议。除了正文指令,一个技能还可能带有 frontmatter,也就是文件顶部的配置字段,以及脚本、参考资料和资源文件。
目标代理能读到这些内容,不代表它会赋予这些内容相同的含义。
迁移至少要检查几个层面:目录能否被发现,字段能否被识别,识别后是否影响行为,hooks 和脚本是否依赖原宿主,以及正文中的命令引用是否仍然有效。例如,一个脚本内部调用原代理的 CLI,即使脚本逐字节复制成功,也没有解决运行依赖。
文件完整性可以证明内容没丢,不能证明技能行为没变。
原文的示例很直观:将 report-builder 从 Claude Code 转到 Codex CLI,预演报告给出 9 条 preserved、4 条 degraded,没有 dropped。这些数字统计的是报告条目,不是文件数量。

正文和配套文件得到了保留,但 allowed-tools 和自定义字段 x-acme-owner 被标记出来,因为目标配置档案尚未验证它们的行为。另外两个 shell 占位符也被提示:在源代理中会展开执行的文本,到了目标端可能只是模型读到的普通文字。
因此,degraded 不一定表示文件内容被删改,也可能表示原有效果无法确认。原文在分类说明处没有完整展开各类定义,不能据此推导出一套更细的判定规则。
先看迁移报告,再决定是否安装
原文介绍的 Skillporter 0.1.0 要求 Node.js 22.20.0 或更新版本。它提供 Claude Code、Codex CLI、OpenCode、DeepSeek Harness 和 Kimi Code 的能力配置档案;独立的 Claude.ai / Skills API 上传配置档案仍是部分支持。
下面两条命令用于安装指定版本,并查看代理列表:
npm install --global @skillporter/cli@0.1.0
skillporter agents
这里要留意第一行的版本固定为 0.1.0,原文所有示例都基于这个版本。
假设技能已经位于 .claude/skills/my-skill,可以先预演迁移到 Codex CLI:
skillporter convert ./.claude/skills/my-skill \
--from claude-code \
--to codex-cli \
--dry-run
关键是最后一行 --dry-run:它只报告计划中的转换,不写入目标文件。my-skill 需要替换成实际存在的技能名称。
审阅报告后,在目标项目中运行同一条转换命令,将 --dry-run 换成 --install --project,并按实际位置调整源路径。这个目标下的安装目录是 .agents/skills/my-skill。
还可以加上 --strict,在修改目标目录前拒绝计划中的损失或暂存阶段的 lint 错误。但不要把退出码理解错:对 convert 而言,退出码 2 表示转换存在损失,不一定表示文件没能写入;在预演中,它表示计划存在损失。
如果只是排查兼容性,可以运行 skillporter inspect ./.claude/skills/my-skill --from claude-code;面向 Codex CLI 检查时,则运行 skillporter lint ./.claude/skills/my-skill --from claude-code --for codex-cli。这两个命令读取技能,不执行其中的脚本或 shell 占位符。
这些判断来自带有来源引用的能力配置档案。缺少已验证证据时,工具会报告不确定性。因此,报告适合帮助人工审阅,不能保证模型行为完全一致。
我的判断
我认可它把迁移拆成「文件有没有保住」和「能力能否延续」两件事。尤其是权限字段和命令占位符,肉眼看着还在,实际效果却可能已经变化,单纯复制目录很难提示这种问题。
作者的检查也支持这个区分:8 次安装均成功并被目标代理发现,196 个复制文件全部与源文件逐字节一致,但仍有 3 次转换报告损失,而且 8 次转换全部产生 lint 警告。安装成功、文件一致、出现警告,可以同时成立。
不过,这组结果不能证明 Skillporter 已经能准确覆盖各种迁移问题。原文没有给出误报率、漏报率,也没有与手工迁移或其他做法进行对照。
README 还记录了 3 个技能在 OpenCode 和 Codex 中的前后对比,测试涉及的行为确实延续了下来。但每个任务、每个代理只运行一次,证据有限,无法判断多次运行是否稳定。
相较于复制目录后直接试用,Skillporter 的价值在于提前指出审阅位置。它仍然需要实际任务验证,特别是宿主专属 hooks 和脚本依赖。0.1.0 尚处于实验性公开 alpha,命令、报告格式和 lint 规则 ID 在 1.0 前都可能变化,不宜把当前输出当成长期固定接口。
能拿来做什么
- 迁移日常 AI 编程技能时,先跑
inspect或面向目标代理的lint,重点审阅权限字段、占位符和宿主命令依赖。 - 正式安装前运行
convert --dry-run,按报告逐项确认损失;需要在写入前拦截问题时,再加上--strict。 - 安装后用技能原本要完成的真实任务做前后对比,同时检查目录发现、脚本运行和输出结果,别只看文件是否齐全。
- 遇到漏报或能力判断错误时,记录源代理版本、目标代理版本、Skillporter 版本和完整命令,并整理最小复现技能,方便定位问题。