技能摆渡 GreenLv/skillferry

skillferry

在 Codex、Claude Code 和 DeepSeek Harness 之间搬运 Skill、全局指令和不含秘密值的 MCP 模板。skillferry 把这些资产放在一份适合 Git 管理的工作区中，逐项说明每个目标能否加载，同时不复制凭据值或运行时状态。

当前在 GitHub 和 PyPI 上发布的最新版本是 0.1.0。

安装并试用

需要 Python 3.11 或更高版本。

使用 pipx 安装 CLI 本体：

$ pipx install skillferry==0.1.0
$ skillferry init my-workspace
$ cd my-workspace

仓库中还包含两个可安装的 Agent Skill。使用 npx skills add GreenLv/skillferry 安装这些 Skill；该命令不会安装 Python CLI 本体。

把 Skill 放进 skills/，编辑 instructions/global.md，或在 mcp/servers.toml 中声明 MCP server。然后检查并应用结果：

$ skillferry plan
$ skillferry apply
$ skillferry doctor

plan 不写文件。apply 发现冲突就停止，并在修改每个受管文件前创建备份。doctor 在目标与工作区一致时返回 0，存在可安全应用的差异时返回 2，存在冲突时返回 3。

可以搬运什么

- Skill 目录，渲染到每个目标的原生 Skill 位置。
- 全局指令，写成受管 marker block 或目标专用文件。
- MCP stdio 模板；环境变量值使用 secret:env/GITHUB_PERSONAL_ACCESS_TOKEN 这类 secret 引用。

它不搬运凭据、会话、记忆、认证状态、任意插件、缓存或整个 Agent home。

从现有配置开始

把 Codex 或 Claude Code 配置中受支持的部分导入新工作区：

$ skillferry import --from codex --output ~/agent-workspace
$ skillferry plan --workspace ~/agent-workspace

导入器只记录工作区格式覆盖的资产。运行 apply 前，请检查生成文件和每项可移植性等级。

创建可公开副本时运行：

$ skillferry export ~/agent-workspace-public

导出命令会扫描复制文件中的凭据形态内容，不展开秘密值引用；发现不安全内容时拒绝写出结果。

可移植性等级

plan 为每项资产和目标报告以下等级之一：

| 等级 | 含义 |
| native | 目标以自己的格式加载该资产，没有已知损失。 |
| translated | skillferry 完成转换，并说明转换方式。 |
| degraded | 资产可用，但存在明确限制或尚未完成的验证。 |
| manual | skillferry 只打印操作说明，不写入目标。 |
| unsupported | 适配器不应用该资产。 |

这些等级描述加载行为，不表示不同 Agent 产品的功能完全等价。完整规则见 可移植性契约。

支持的目标

| 资产 | Codex | Claude Code | DeepSeek Harness |
| Skills | native | native | native |
| 全局规则 | native | translated | native |
| MCP stdio | translated | translated | translated |
| MCP HTTP/SSE | manual | manual | manual |
| 扩展/插件 | manual | manual | manual |

精确目标路径、加载证据和已知损失记录在 Agent 能力矩阵中。

Secret、本地修改与回滚

- 工作区中的 MCP 值必须使用 secret:env/... 或 secret:file/... 引用。解析后的真实值只写入本机目标配置。
- 逐路径哈希账本用于区分生成变更和手工编辑。冲突必须使用 --resolve <id>=adopt|overwrite|keep-local 决策，不会被静默覆盖。
- 原始备份以 0600 权限保存在本机，同时生成脱敏副本供检查；多目标应用失败时，已修改的目标会回滚。
- [protect] 声明把认证、会话、数据库、缓存和其他指定路径排除在工作区所有权之外。

完整边界见安全威胁模型。

工作区结构

schema_version = 1

[skills]
directory = "skills"
default_targets = ["codex", "claude", "dsh"]

[instructions]
common = "instructions/global.md"

[mcp]
registry = "mcp/servers.toml"

[protect]
paths = []

目标、平台、主机和本地覆盖配置按该顺序合并。列表整体替换，字典深合并，plan 会显示每个值的来源。可运行示例位于 examples/starter-workspace。

文档与开发

- 文档索引
- 可移植性契约
- Agent 能力矩阵
- 安全威胁模型
- 分发渠道
- 0.1.0 发布验收
- 更新日志

python -m pip install -e '.[dev]'
pytest
ruff check .
python scripts/audit_public_tree.py .

许可证

Apache-2.0。见 LICENSE。