Capabilities file

Your project’s source of truth is capabilities.yaml or capabilities.json at the project root. Edit the file, then run capa install (or capa add) so capa materializes provider files and wiring from that declaration.

Capa does not auto-discover skills or MCP entries from provider folders. If it is not in the capabilities file, capa will not manage it.

Skeleton

providers:
  - cursor
  - claude-code

options:
  toolExposure: expose-all  # expose-all | on-demand | none
  # security: { blockedPhrases, allowedCharacters }
  # requiresCommands: [ { cli, description? } ]

# agents: { base?, additional? }

skills: []
servers: []
tools: []
# rules: []
# plugins: []
# hooks: []
# subagents: []

providers is optional. When omitted, capa resolves providers at install time from --provider, a previous install recorded in the database, or an interactive prompt.

Sections

Section	What you declare	Guide
`providers`	Which agent clients capa installs for	Providers
`options`	`toolExposure`, optional `security`, optional `requiresCommands`	Tool exposure
`skills`	Skills to install and bind tools to	Skills
`servers`	MCP servers (local subprocess or remote HTTP)	Servers
`tools`	MCP tool bindings and command tools	Tools
`rules`	Provider rules / instruction snippets	Rules
`plugins`	Plugin packages that ship skills, servers, and more	Plugins
`hooks`	Lifecycle hooks capa installs into provider configs	Hooks
`agents`	Base + additional content for `AGENTS.md` / `CLAUDE.md`	Agent instructions
`subagents`	Named sub-agents with skills, tools, and instructions	Sub-agents

After you edit

Save capabilities.yaml (or .json).
Run capa install.
Restart the capa server only if you changed server commands, server env vars, or toolExposure (capa restart). Skill, rule, hook, and agents content take effect on the next install.

For how managed install differs from --passthrough, see Managed vs passthrough. For pinned remotes and the on-disk cache, see Lockfile and cache.