skillswap

Port, install, validate, repair, and safely roll back Agent Skills across every filesystem agent.

skillswap is a universal Agent Skills framework: one skill authored once, ported to Claude Code, Codex, GitHub Copilot (VS Code), Gemini CLI / Antigravity, and the universal .agents/skills convention — with hash-verified receipts so every port and install can be rolled back byte-for-byte.

Why skillswap

Agent skills are just a SKILL.md file with YAML frontmatter plus optional companion files, but every agent reads them from a different directory and tolerates a different frontmatter dialect. skillswap normalizes that:

• Port one skill (or a whole directory) to any or all of the five targets.
• Shop GitHub for skills with gh skill search and port them in one command.
• Install a ported output into project, user, or shared agent locations.
• Doctor validates skills in place and reports what an agent will or will not understand.
• Repair fixes common issues (name, directory, boolean fields, unknown context) automatically.
• Rollback undoes a port or install from its receipt — even after files changed (quarantine).

Every mutating command supports --dry-run, --json, --force, and --yes.

Requirements

• Node.js >= 20.12
• gh CLI >= 2.90 for skillswap shop (not needed for local ports)
• git (for github: sources)

Install

npm install -g skillswap

or run straight from a checkout:

npm install
npm run dev -- --help

The package exposes two binaries: skillswap and sp.

Quick start

Port a local skill directory to all five agents:

skillswap port ./my-skill --output ./out

Pipe skills straight from GitHub's skill search:

gh skill search terraform --json skillName,description,namespace,path,repo,stars |
  skillswap port --stdin-format gh-skill --to all --output ./out --yes --accept-remote-risk

Or shop interactively (checkbox picker when run in a terminal):

skillswap shop terraform --to claude-code,codex

Install a ported output into the current project (.claude/skills, .codex/skills, .github/skills, .gemini/skills, .agents/skills):

skillswap install ./out --scope project

Validate what the agents will actually load:

skillswap doctor

Roll back a port + install from its receipt:

skillswap rollback ./out/skillswap.receipt.json --yes

Commands

| Command | Description | | --- | --- | | list [dir] | List installed skills across all five agents | | shop <query> | Search GitHub for skills (gh skill search) and port selections | | port <sources...> | Port local skills, github:owner/repo/path sources, or stdin skill search JSON | | install <output> | Install a ported output into agent locations | | doctor [dir] | Validate skills in every agent location | | repair [targets...] | Fix name, directory, boolean, and context issues automatically | | rollback <receipt> | Restore a port/install from its receipt (hash-verified) |

Global flags

Every mutating command accepts:

• --dry-run — plan and check conflicts without writing anything
• --json — machine-readable output (safe for piping; never prompts)
• --force — overwrite conflicting files with timestamped backups
• --yes — skip all confirmation prompts

Target agents

| Agent | Project directory | User directory | Notes | | --- | --- | --- | --- | | claude-code | .claude/skills | ~/.claude/skills | Strict consumer; only portable profile emitted | | codex | .codex/skills | ~/.codex/skills | Also reads .agents/skills | | copilot | .github/skills | ~/.copilot/skills | Also reads .claude/skills and .agents/skills | | gemini | .gemini/skills | ~/.gemini/skills | Gemini CLI / Antigravity | | universal | .agents/skills | ~/.agents/skills | Universal convention read by most CLI agents |

Aliases: claude → claude-code, codex/openai-codex → codex, copilot/github-copilot/vscode → copilot, gemini/gemini-cli/antigravity → gemini, all → every agent.

Install scopes

| Scope | Writes to | | --- | --- | | project | <project-root>/<agent>/skills for each target agent | | user | ~/.claude/skills, ~/.codex/skills, … per agent | | shared | ~/.agents/skills only (universal convention) |

Universal-first resolution: sources are always discovered from .agents/skills first, then the vendor directories.

Conversion behavior

Each target adapter has a key policy for the canonical SKILL.md frontmatter:

| Key | claude-code | codex | copilot | gemini | universal | | --- | --- | --- | --- | --- | --- | | name, description, license, compatibility, metadata, allowed-tools | keep | keep | keep | keep | keep | | context, argument-hint, user-invocable, disable-model-invocation | strip | strip | keep* | strip | strip |

* Copilot keeps VS Code–specific invocation fields only when the source skill is already a Copilot skill; otherwise they are stripped with a vendor-key-stripped warning. Stripped fields are recorded in the receipt as diagnostics, so nothing is lost silently.

Companion files are copied into every target directory. Scripts are copied but agents gate execution behind consent prompts; skillswap doctor warns when a skill ships scripts.

GitHub sources and the shop

skillswap shop <query> shells out to gh skill search (GitHub CLI v2.90+). Results are provenance-tagged (provider: github-cli-skill-search) in every receipt so you can audit where a skill came from.

Remote sources are cloned into a temporary directory (shallow, pinned to the resolved commit) and pass through a risk scan before anything is touched:

• 🔴 danger — symbolic links, binaries/archives, binary content, dangerous command patterns, size/file-count budget exceeded
• 🟡 warning — scripts, machine-specific absolute user paths

If any danger finding exists, the port refuses unless you pass --accept-remote-risk.

Security posture

• Blast radius — ports write only to the requested output directory; installs write only to the requested scope's directories.
• Risk gates — remote sources are scanned before use and refused on danger findings unless explicitly accepted.
• Receipts — every port/install writes skillswap.receipt.json (pointer) plus the canonical receipt in <output>/.skillswap/receipts/<id>.json (schemaVersion: 2), recording every file written, its hash, and any backup created.
• Rollback — restores from backups only after verifying the current file still matches the recorded hash. Files edited since the port are quarantined (or refused without --force) rather than silently overwritten.
• No telemetry, no network calls except the explicit gh skill search and git clone you trigger.

Development

npm run typecheck   # tsc --noEmit
npm test            # node:test via tsx
npm run build       # tsc -p tsconfig.build.json → dist/
npm pack --dry-run  # inspect the published tarball

The test suite runs on Node's built-in node:test runner — no test framework dependency.

License

MIT — see LICENSE.