portage

Port, install, validate, repair, and safely roll back custom agents across every filesystem agent — one agent, every IDE.

portage is the sibling of skillport (skillswap): the same architecture, pipeline, and safety guarantees — but for custom agents instead of skills.

Supported ecosystems

| Vendor | Format | Project root | User root | |---|---|---|---| | Copilot / VS Code | .agent.md | .github/agents | ~/.copilot/agents | | Antigravity / Gemini CLI | agent.md | .agents/agents | ~/.gemini/config/agents | | Claude Code | .md | .claude/agents | ~/.claude/agents | | opencode | .md | .opencode/agents | ~/.config/opencode/agents | | Cursor | .md | .cursor/agents | ~/.cursor/agents | | Codex | TOML | .codex/agents | $CODEX_HOME/agents |

Install

npm install -g portage-cli

Usage

portage has two core commands: port (convert) and install (deploy).

Quick: port + install in one step

# Port from a GitHub repo and install into user-scope locations
portage port github:owner/repo/path/to/agents --to opencode --scope user

# Port from a local directory and install into a specific project
portage port ~/.copilot/agents --to opencode --scope project --project-root ./my-app

The --scope flag triggers a two-phase commit: agents are first converted and staged in an output directory, then copied into the real ecosystem locations (.opencode/agents/, .github/agents/, etc.). A receipt is saved so rollback can undo everything.

Step by step: port first, install later

# Step 1 — Convert agents and write to an output directory
portage port github:owner/repo/path/to/agents --to opencode --out ./ported

# Step 2 — Review the output, then install from the receipt
portage install ./ported --scope user

This is useful when you want to inspect or edit converted agents before deploying them.

Other commands

# List installed agents across all ecosystems
portage list

# Validate installed agents
portage doctor

# Repair invalid agent directories
portage repair

# Roll back the last port + install
portage rollback

Source types

# Local directory of agents (discovers all agents inside)
portage port ~/.copilot/agents --to opencode

# GitHub repo
portage port github:owner/repo/path/to/agents --to all

# Individual agent file
portage port ./my-agent.md --to claude-code

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

Safety

• Two-phase commit with .bak-<timestamp> backups and atomic writes
• Hash-verified receipts and rollback
• Quarantine on conflict (.portage-conflict-<id>)
• Risk scanning of remote sources before materialization
• Never emits unverified tool names (a misspelled tool can hang a subagent)

Development

npm install
npm run check   # typecheck + test + build

See docs/portage-design.md for the full design contract.

License

MIT