Managed vs passthrough

capa can apply your capabilities in two ways. Pick one path per workflow and stick to it so you do not mix managed MCP entries with native-only writes.

Comparison

	Managed (`capa install`)	Passthrough (`--passthrough`)
Source	`capabilities.yaml` / `.json`	Same file for `capa install --passthrough`, or `capa add --passthrough` writing native files
Provider files	Yes: skills, MCP client config, rules, hooks, agents blocks, and related managed artifacts	Yes: provider-native files only
capa server / MCP proxy	Yes: install starts and uses the local capa server	No: no capa server or proxy management on this path
Lockfile	Writes / updates `capabilities.lock` with pinned refs	Focus is native file writes; not the managed server/proxy path
Secrets	Web UI prompts or `-e .env`; stored in `~/.capa/capa.db`	Expand `${VarName}` from the environment / `-e` when writing native config; no capa proxy
Typical goal	One declarative file, shared tooling, `capa sh`, tool exposure modes	Drop skills/plugins/MCP into the provider’s own layout without running capa’s gateway

When to use managed

Use managed install when you want capa to own the loop:

Declare everything in the capabilities file and re-apply with capa install.
Run tools through capa’s MCP proxy or capa sh.
Use options.toolExposure, credentials in ~/.capa/capa.db, and the lockfile/cache pipeline.
Keep multiple providers in sync from one file.

capa install
capa install -e          # load .env instead of the credential web UI
capa install -p cursor   # single provider

When to use passthrough

Use --passthrough when you only need native provider files and do not want capa to manage a server or MCP proxy for that install/add:

capa install --passthrough
capa add <source> --passthrough -p cursor

Passthrough is useful for one-off native installs, environments that forbid a local capa gateway, or workflows where the provider itself should own plugins and MCP entries.

What `capa install --passthrough` does with rules and sub-agents

Rules use the same placement as managed install: shared AGENTS.md handling, Gemini CLI’s GEMINI.md when it shares AGENTS.md, nested files for directory appliesTo globs, and the same visibility/scope conflict reporting under options.rules.conflicts. See Rules.
Gemini CLI: when a rule block is written to the file Gemini reads, capa adds that file to .gemini/settings.json → context.fileName so Gemini actually loads it. Unlike managed install, passthrough records no ownership in capabilities.lock, so capa clean won’t remove that entry.
Summary counts: rules that apply to no active provider are counted as skipped, and rules skipped because of a conflict in error mode are counted as failed.
Sub-agents honor their providers allow-list, just like managed install.