skillferry

简体中文 | Distribution | Introduction | Changelog

Move skills, global instructions, and non-secret MCP templates between Codex, Claude Code, and DeepSeek Harness. skillferry keeps them in one Git-friendly workspace, shows what each target can load, and never copies credentials.

The latest published version is 0.1.0 on GitHub and PyPI.

Install and try it

Python 3.11 or newer is required.

Install the CLI itself with pipx:

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

The repository also contains two installable Agent Skills. Install those Skills with npx skills add GreenLv/skillferry; this does not install the Python CLI.

Add skills under skills/, edit instructions/global.md, or declare MCP servers in mcp/servers.toml. Then review and apply the result:

$ skillferry plan
$ skillferry apply
$ skillferry doctor

plan never writes. apply stops if it finds a conflict and backs up every file it owns before changing it. doctor exits 0 when the rendered targets match the workspace, 2 for safe drift, and 3 for a conflict.

What skillferry moves

• Skill directories, rendered into each target's native Skill location.
• Global instructions, written as managed marker blocks or target-specific files.
• MCP stdio templates whose environment values are secret references such as secret:env/GITHUB_PERSONAL_ACCESS_TOKEN.

It does not move credentials, sessions, memories, authentication state, arbitrary plugins, caches, or an agent's complete home directory.

Start from an existing setup

Import the supported parts of a Codex or Claude Code setup into a new workspace:

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

The importer records only assets covered by the workspace schema. Review the generated files and every portability grade before running apply.

To create a shareable copy, use:

$ skillferry export ~/agent-workspace-public

Export scans copied files for credential-shaped content, does not expand secret references, and refuses to write an unsafe result.

Portability grades

plan reports one of these grades for every asset and target:

Grade	Meaning
native	The target loads the asset in its own format with no known loss.
translated	skillferry converts the asset and names the transformation.
degraded	The asset works with a stated limitation or incomplete verification.
manual	skillferry prints instructions instead of writing the target.
unsupported	The adapter does not apply the asset.

These grades describe loading behavior, not feature equivalence between agent products. The full rules are in the portability contract.

Supported targets

Asset	Codex	Claude Code	DeepSeek Harness
Skills	native	native	native
Global rules	native	translated	native
MCP stdio	translated	translated	translated
MCP HTTP/SSE	manual	manual	manual
Extensions/plugins	manual	manual	manual

The exact target paths, loading evidence, and known losses are maintained in the agent matrix.

Secrets, local edits, and rollback

• Workspace MCP values must use secret:env/... or secret:file/... references. Resolved values are written only to the local target config.
• A per-path hash ledger distinguishes generated changes from hand edits. Conflicts require --resolve <id>=adopt|overwrite|keep-local; they are never overwritten silently.
• Backups stay local with mode 0600. Redacted copies are also produced for inspection, and a failed multi-target apply rolls back the targets already changed.
• [protect] declarations keep authentication, sessions, databases, caches, and other named paths outside workspace ownership.

See the threat model for the complete boundary.

Workspace layout

schema_version = 1

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

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

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

[protect]
paths = []

Target, platform, host, and local overlays are merged in that order. Lists replace; dictionaries deep-merge; plan shows the origin of each value. A runnable example is available in examples/starter-workspace.

Documentation and development

• Documentation index
• Portability contract
• Agent matrix
• Threat model
• Distribution
• Release 0.1.0 acceptance
• Changelog

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

License

Apache-2.0. See LICENSE.