Introduction

capa is an agentic capabilities manager. You declare skills, MCP servers, tools, rules, hooks, plugins, and agent instructions in one capabilities.yaml (or .json), then let capa apply that file to your coding agents.

If you juggle Cursor, Claude Code, Codex, or other providers — and you’re tired of copying skills, hand-editing MCP configs, and drifting secrets — capa is for you.

What you get

• One source of truth — the capabilities file decides what exists; capa doesn’t auto-discover leftover provider folders.
• Consistent installs — skills, MCP proxies, rules, hooks, and plugins land where each provider expects them.
• Secrets as placeholders — use ${VarName} in the file; capa prompts or loads values at install time.
• A local server — after a managed install, capa serves MCP and tooling around localhost:5912.

Three modes

Pick the mode that matches how you want provider files to land:

Mode	What it does	When to use it
Managed	capa install writes capa-managed provider configs into the project and starts the capa server.	You want the repo to carry the wired-up agent setup.
Wrap	capa wrap <provider> runs the agent from a shadow workspace under ~/.capa/workspaces without writing provider configs into the real repo.	You want a clean working tree and ephemeral provider layout.
Passthrough	capa add --passthrough / capa install --passthrough writes native provider files and skips capa proxy management.	You want provider-native files only, not the capa MCP server loop.

Tip

Managed and wrap both start from the same capabilities file. Passthrough deliberately bypasses capa’s managed proxy path.

Wrappable providers

You can wrap: cursor (GUI; CLI alias agent), claude-code (alias claude), codex, gemini-cli, opencode, qwen-code, kiro-cli, iflow-cli, and kimi-cli. GitHub Copilot is not wrappable yet.

Next steps

1. Install capa
2. Follow the managed quick start or the wrap quick start
3. Read How capa works when you want the mental model