skillport

skillport 快速入门

一句话卖点: 写一份 SKILL.md，自动检测在 Claude Code / Codex / Gemini CLI 三个平台上的行为差异

这是什么?适合谁?

skillport 是 Agent Skills 的跨平台兼容性测试器。它的核心理念直击 Agent Skills 生态的核心痛点：SKILL.md 格式虽然”开放”，但 Claude Code、Codex、Gemini CLI 三个平台对同一份 SKILL.md 的理解和执行存在微妙差异——你写了一份 Skill，在 Claude Code 上完美运行，到了 Codex 上可能行为不同，到了 Gemini CLI 上甚至可能完全不生效。

skillport 把这种差异从”踩坑后才发现”变成”发布前就知道”。你写好 SKILL.md，skillport 自动在三个平台上运行相同的测试用例，对比输出结果，告诉你哪里不兼容、哪里行为有差异。

适合正在开发或维护 Agent Skills 的开发者，尤其是需要确保 Skills 在多个平台上都能正常工作的场景。也适合 Skills 市场的运营者，用于验证提交的 Skills 的跨平台兼容性。

TypeScript CLI 工具，MIT 开源。

准备工作

1. Node.js 18+ 环境
2. 本地安装 Claude Code、Codex CLI、Gemini CLI（至少一个）
3. 一份待测试的 SKILL.md 文件
4. 各平台的 API Key 或认证配置

3步快速上手

第1步: 安装 skillport

git clone https://github.com/suifeng156/skillport.git
cd skillport
npm install
npm run build

第2步: 配置平台连接

skillport 需要连接到你本地安装的 Agent 平台。配置各平台的认证信息：

# 配置 Claude Code
npx skillport config --platform claude-code --api-key YOUR_ANTHROPIC_KEY
# 配置 Codex
npx skillport config --platform codex --api-key YOUR_OPENAI_KEY
# 配置 Gemini CLI
npx skillport config --platform gemini --api-key YOUR_GOOGLE_KEY

第3步: 运行兼容性测试

npx skillport test --skill ./my-skill/SKILL.md --platforms claude-code,codex,gemini

skillport 会在三个平台上分别执行你的 Skill，然后输出差异报告。

常见踩坑

1. 需要三个平台的 CLI 都正确安装并认证——缺任何一个，对应平台的测试会跳过
2. 测试会真实调用各平台的 API，会产生费用——建议先用简单 Skill 验证流程
3. 各平台的 CLI 路径可能不同，skillport 默认从 PATH 中查找，可通过 —cli-path 手动指定
4. 测试结果可能因 LLM 的非确定性而每次略有不同——建议多次运行取交集
5. 目前仅支持 Claude Code、Codex、Gemini CLI 三个平台，不支持其他 Agent 框架
6. 项目刚发布（2 星），API 可能在未来版本中变化

初级用法

1. 单平台测试：只测一个平台，快速验证 Skill 在该平台上的行为
2. 差异对比：在两个平台间对比同一 Skill 的执行结果
3. 批量测试：一次测试多个 SKILL.md 文件
4. CI 集成：将 skillport 集成到 GitHub Actions，每次 PR 自动检测兼容性

高级玩法

1. 自定义测试用例：编写平台特定的测试场景，覆盖边界情况
2. 差异阈值配置：设置可接受的差异程度，只有超过阈值的差异才报告
3. 回归测试：保存基线结果，后续版本对比是否引入新差异
4. 报告导出：将兼容性报告导出为 JSON/Markdown，用于文档或分享

小技巧

1. 先用最简单的 Skill（如”回复 Hello World”）验证三个平台连接正常
2. 测试时关闭各平台的缓存功能，确保每次都是全新执行
3. 对于复杂 Skill，分模块测试比一次性全测更容易定位问题
4. 关注 skillport 的 GitHub Issues，了解已知的平台差异
5. MIT 开源，可以 fork 后添加对其他 Agent 平台的支持

常见问题 FAQ

Q1: skillport 和直接手动在三个平台上测试有什么区别？ A: skillport 自动化了”同一输入→三平台执行→结果对比”的流程，手动做需要大量重复操作且容易遗漏差异。来源：GitHub README。

Q2: 测试一次大概花多少钱？ A: 取决于 Skill 的复杂度。简单 Skill（单次 LLM 调用）三个平台合计约 $0.01-0.05。复杂 Skill（多次工具调用）可能 $0.10-0.50。来源：各平台 API 官方定价（OpenAI/Anthropic/Google 官网定价页）。

Q3: 支持哪些 Agent 平台？ A: 目前支持 Claude Code、Codex CLI、Gemini CLI。项目架构支持扩展，可以贡献新平台的适配器。来源：GitHub 代码结构。

Q4: 能检测到什么类型的差异？ A: 输出内容差异、工具调用差异、执行步骤差异、错误处理差异。不检测性能差异（响应时间等）。来源：项目功能描述。

Q5: 是免费的吗？ A: skillport 本身 MIT 开源免费。但测试过程调用各平台 API 会产生费用。来源：GitHub LICENSE。