/capabilities-manager

name: capabilities-manager
description: Manage capa CLI configuration — `capabilities.yaml` / `capabilities.json`, skills, MCP servers, tools, hooks, sub-agents, rules, plugins, AGENTS.md / CLAUDE.md, security options, tool exposure modes, `capa wrap` shadow workspaces, `--passthrough` native writes, registries (including Claude marketplaces), activity traces, and the local Web UI. Use whenever the user edits the capabilities file, runs any `capa` command (init, install, add, wrap, clean, sh, start/stop/restart/status, auth, upgrade, cache, registry), wires up an MCP server, adds a skill from GitHub / GitLab / a registry / a remote URL / a local path, configures secrets via `${VarName}` placeholders, installs lifecycle hooks, defines sub-agents, or troubleshoots a failed install. Use even when the user only names a fragment ("add a skill", "wire up brave search", "wrap cursor", "block this phrase in skills") without saying "capa" — if a `capabilities.yaml` or `capabilities.json` lives at the project root, this is almost certainly the right skill. If the project does NOT yet have a capabilities file, point at the `bootstrap` skill instead.

Capabilities Manager

The capa CLI keeps a single source-of-truth file — `capabilities.yaml` (or `.json`) — that describes everything an agent can do in this project: skills, MCP servers, tools, hooks, sub-agents, rules, plugins, and per-provider files (`AGENTS.md`, `CLAUDE.md`). Editing that file and running the right `capa` command is the whole loop.

This skill is the routing layer for that loop. The actual command reference, schema, full YAML examples, and troubleshooting tables live in `references/`. Load the one you need rather than re-deriving its contents — they are kept up to date and are the authoritative source.

How capa works (one screen)

1. **The file is the source of truth.** `capabilities.yaml` declares what gets installed. Capa never auto-discovers anything from `.claude/`, `.cursor/`, etc. — if it's not in the file, capa won't manage it. (Onboarding an already-configured project is the `bootstrap` skill's job.) 2. **`capa install` writes everything.** Skill directories under each provider, MCP client config (`.mcp.json`, `.cursor/mcp.json`, etc.), `AGENTS.md` / `CLAUDE.md` blocks, hook entries, rules — all rewritten from the file. Anything labeled `name: capa:<id>` is capa's; entries the user authored by hand are left alone. Plugins unpack into the same primitives (skills, servers, rules, sub-agents, hooks). 3. **`capa clean` removes only what capa wrote.** Safe to run; doesn't touch user-authored files or settings entries. Passthrough writes (`capa add --passthrough` / `capa install --passthrough`) are **not** managed — `capa clean` will not remove them. 4. **A background server at `localhost:5912`** handles credential prompts, tool execution (`capa sh`), MCP endpoints, the Web UI capabilities editor, registries, and the Activity feed. Started by `capa init` / `capa install`; lifecycle is `capa start | stop | restart | status`. 5. **Secrets are `${VarName}` placeholders** anywhere in the file. Capa prompts for them via web UI on install, or loads from `.env` with `capa install -e`. 6. **`capa wrap <provider>`** runs the agent from a shadow workspace under `~/.capa/workspaces/` so provider dirs never pollute the real repo. Mutating commands refuse to run inside a wrap workspace — always edit/install from the real project path.

Routing — load the reference that matches the task

| If the user is… | Read first | Then | |---|---|---| | Running a CLI command (init/install/add/wrap/clean/sh/server/auth/cache/registry/upgrade) or asking what flags exist | `references/commands.md` | Run the command and report results | | Editing the file — adding a skill, server, tool, hook, sub-agent, rule, plugin, agents block, security / activity setting | `references/capabilities-schema.md` | Edit `capabilities.yaml`; run `capa install` | | Asking how to wire up a common pattern (web search, wrap, passthrough, on-demand mode, plugins, registries, etc.) | `references/workflows-and-examples.md` | Adapt the closest example | | Hitting an install error, wrap failure, credential prompt issue, server crash, missing tools, stale cache, TLS error, blocked phrase | `references/troubleshooting.md` | Apply the diagnostic flow listed for that symptom |

The references are sized for selective reads (each ≤ ~600 lines, with table-of-contents at the top of the larger ones). Don't load all four if only one applies.

Pitfalls worth heading off

These are the mistakes an agent makes when it improvises the YAML instead of consulting the schema. Skim them before writing or editing a capabilities file.

`@` vs `::` in `def.repo`

The repo string used by `skills`, `rules`, `plugins`, hook sources, and agent snippets has two grammars with different resolution semantics:

• `owner/repo@<basename>` — capa **searches** the repo recursively for an entry matching `<basename>` (a directory containing `SKILL.md` for skills, a file with that basename for rules / snippets). The right-hand side must have no slashes.
• `owner/repo::<exact/path>` — **no search**; the path must point exactly at the right thing from the repo root.

Use `@` when the name is unique and stable. Use `::` when the file location is part of what the user told you (e.g. "the file is at `rules/typescript.md`") or when collisions are possible. Both forms accept pinning: `:v1.2.0` (tag/branch) or `#abc1234` (commit SHA).

`${VarName}` is a **capa** placeholder, not a shell variable

`${BraveApiKey}` in `capabilities.yaml` is resolved by capa at install time from its credential store or a `.env` file. It has nothing to do with the runtime environment of any spawned process. In particular: **providers do not export tool input as env vars to hooks** — each fired hook receives a JSON payload on **stdin**. If a hook needs to inspect the command being run, write a local script that reads stdin w