Capabilities File

The capabilities file is the heart of CAPA. It's a declarative configuration that defines everything your agent can do: skills, servers, and tools.

File Format

CAPA supports both YAML and JSON formats:

capabilities.yaml (default, recommended for readability)
capabilities.json (useful for programmatic generation)

Initialize a capabilities file with:

# YAML (default)
capa init

# JSON
capa init --format json

File Structure

A capabilities file has the following main sections:

providers:
  - cursor
  - claude-code

options:
  toolExposure: on-demand   # expose-all | on-demand | none
  # security: { blockedPhrases: [...], allowedCharacters: "" }

plugins: []
# Optional: remote MCP plugins (see Plugins docs)

# Optional: manage AGENTS.md / CLAUDE.md content
# agents:
#   base:
#     ref: https://raw.githubusercontent.com/org/repo/main/AGENTS.md
#   additional:
#     - type: inline
#       id: my_snippet
#       content: "Custom agent instructions here."

# Optional: install rules into each provider's native rules system
# rules:
#   - id: commit-style
#     type: inline
#     appliesTo: ["**/*"]
#     content: "Use Conventional Commits."

# Optional: declarative lifecycle hooks (see Hooks docs)
# hooks:
#   - id: audit-shell
#     on: beforeShell
#     command: 'echo "$(date) $TOOL_INPUT" >> ~/.capa/audit.log'

skills:
  - id: skill-id
    type: inline|remote|github|gitlab|local|installed
    def:
      # skill definition

servers:
  - id: server-id
    type: mcp
    def:
      # server definition

tools:
  - id: tool-id
    type: mcp|command
    def:
      # tool definition

{
  "providers": ["cursor", "claude-code"],
  "options": {
    "toolExposure": "expose-all"
  },
  "plugins": [],
  "agents": {
    "additional": [
      {
        "type": "inline",
        "id": "my_snippet",
        "content": "Custom agent instructions here."
      }
    ]
  },
  "rules": [
    {
      "id": "commit-style",
      "type": "inline",
      "appliesTo": ["**/*"],
      "content": "Use Conventional Commits."
    }
  ],
  "skills": [
    {
      "id": "skill-id",
      "type": "inline",
      "def": {}
    }
  ],
  "servers": [
    {
      "id": "server-id",
      "type": "mcp",
      "def": {}
    }
  ],
  "tools": [
    {
      "id": "tool-id",
      "type": "mcp",
      "def": {}
    }
  ]
}

Sections

1. Providers

List of MCP clients where skills should be installed. CAPA ships with built-in support for many providers. The common ones:

cursor: Cursor IDE.
claude-code: Claude Code.
codex: OpenAI Codex.
github-copilot: GitHub Copilot.
opencode: OpenCode.
gemini-cli, windsurf, roo, cline, augment, amp, kilo, continue, goose, droid, and others.

For the complete list, run capa init in an empty project (CAPA prompts with every registered provider), or browse the provider registry source.

You can also install for a single provider on the fly without editing the file:

capa install --provider cursor
capa install -p claude-code

This flag takes precedence over the providers array in the file and over any previously saved selection for the project.

2. Options

Configuration for CAPA behavior:

toolExposure

Controls how tools are exposed to the agent. Three modes are available:

expose-all (default): Every tool's JSON schema is published up front via MCP. Best for simple setups.
on-demand: Only two meta-tools (setup_tools and call_tool) are exposed. Schemas are loaded lazily, reducing context window usage by up to 40%.
none: Skips all MCP config writes. The agent reaches tools via capa sh shell commands. Maximum context savings.

Benchmarks show both on-demand and none deliver ~19% cost savings vs expose-all with zero quality regression. See the Tool Exposure page for details and the Benchmarks for full data.

security

Optional security options for skill installation. Omit a property (or comment it out) to disable that feature. Only present properties are applied. Omit the security block entirely to disable both.

blockedPhrases - Block skill installation if any skill file contains forbidden phrases. Omit or comment out to disable.

Inline: Provide a list of phrases: blockedPhrases: ["eval(", "exec("]
From file: Reference a .txt file (one phrase per line, relative to capabilities file): blockedPhrases: { file: "./blocked-phrases.txt" }

When a blocked phrase is detected during capa install, installation stops immediately and reports which skill (or plugin skill) and file contains the phrase.

allowedCharacters - When present, characters outside the allowed set are replaced with spaces during installation. Omit or comment out to disable entirely.

A hardcoded baseline is always preserved regardless of this setting: tab, LF, CR, and all printable ASCII (U+0020–U+007E). This means characters like -, :, ", ', newlines, and all keyboard symbols are never stripped. The allowedCharacters value specifies extra Unicode ranges to allow on top of the baseline.

Empty string "": baseline only. Strips non-ASCII Unicode (emoji, special chars).
[\\u00A0-\\uFFFF]: allow all printable Unicode including emoji
Omit / comment out: sanitization is disabled

options:
  toolExposure: expose-all
  security:
    blockedPhrases:
      - "eval("
      - "exec("
    allowedCharacters: ""  # baseline only: strips non-ASCII Unicode
    # allowedCharacters: "[\u00A0-\uFFFF]"  # allow all Unicode including emoji

{
  "options": {
    "toolExposure": "expose-all",
    "security": {
      "blockedPhrases": ["eval(", "exec("],
      "allowedCharacters": ""
    }
  }
}

requiresCommands

Optional list of CLI commands that must be available on the user's system before capa install proceeds. If any command is missing, installation stops immediately with a clear error.

options:
  requiresCommands:
    - cli: docker
      description: Required to run containerised tools
    - cli: node
    - cli: git
      description: Used by GitHub skill sources

{
  "options": {
    "requiresCommands": [
      { "cli": "docker", "description": "Required to run containerised tools" },
      { "cli": "node" },
      { "cli": "git", "description": "Used by GitHub skill sources" }
    ]
  }
}

Each entry has:

cli (required): The executable name to check (e.g., docker, node, python3)
description (optional): A hint shown when the command is missing

During capa install, each entry is verified using which (Unix) or where (Windows). Omit requiresCommands (or leave it empty) if you have no CLI prerequisites.

For the full workflow (on-demand steps, when to use each mode, and performance data), see Tool Exposure.

3. Plugins

Optional list of remote MCP plugins (GitHub or GitLab). When you run capa install, CAPA clones each plugin, reads its manifest, installs its skills, and merges its tools and servers into your project. See the Plugins documentation for details.

4. Agents

Optional section that manages AGENTS.md or CLAUDE.md in the project root. These are the standard files that AI coding agents read for project-specific instructions. The section supports a remote base file plus a list of snippets sourced from inline text, raw URLs, GitHub, or GitLab. See the Agent Instructions documentation for details.

5. Rules

Optional section that installs short, focused instruction documents into each provider's native rules system: .cursor/rules/*.mdc, .windsurf/rules/*.md, .github/instructions/*.instructions.md, etc. Providers without a dedicated rules directory (Claude Code, Codex, OpenCode, …) receive the same content folded into AGENTS.md / CLAUDE.md as a capa-managed marker block. Rules support inline, remote, github, and gitlab source types, plus per-rule appliesTo globs and alwaysApply flags. See the Rules documentation for details.

6. Skills

Modular knowledge packages that teach agents when and how to use tools. See the Skills documentation for details.

7. Servers

MCP servers that provide tools (local subprocesses or remote HTTP servers). See the Servers documentation for details.

8. Tools

Executable capabilities (MCP tools or shell commands). See the Tools documentation for details.

9. Hooks

Optional declarative lifecycle hooks that are mapped to each provider's native hook system. Hooks support command and prompt types, with bodies sourced from inline text, remote URLs, GitHub/GitLab repos, or local files. See the Hooks documentation for details.

Variable Substitution

Use ${VariableName} for sensitive values like API keys:

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}
        CUSTOM_VAR: ${MyCustomVariable}

{
  "servers": [
    {
      "id": "brave",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}",
          "CUSTOM_VAR": "${MyCustomVariable}"
        }
      }
    }
  ]
}

When you run capa install, CAPA will prompt for these values via a web UI, or you can provide them via a .env file. See the Credentials documentation for more details.

Complete Example

Here's a complete capabilities file with web research capabilities:

providers:
  - cursor

options:
  toolExposure: on-demand

skills:
  - id: web-researcher
    type: inline
    def:
      content: |
        ---
        name: web-researcher
        description: Search the web for information
        ---
        Use the brave.search tool to find current information online.
      requires:
        - '@brave.search'

servers:
  - id: brave
    type: mcp
    description: Brave web search
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: search
    type: mcp
    description: Search the web using Brave Search
    def:
      server: "@brave"
      tool: brave_web_search

{
  "providers": ["cursor"],
  "options": {
    "toolExposure": "on-demand"
  },
  "skills": [
    {
      "id": "web-researcher",
      "type": "inline",
      "def": {
        "content": "---\nname: web-researcher\ndescription: Search the web for information\n---\nUse the brave.search tool to find current information online.",
        "requires": ["@brave.search"]
      }
    }
  ],
  "servers": [
    {
      "id": "brave",
      "type": "mcp",
      "description": "Brave web search",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}"
        }
      }
    }
  ],
  "tools": [
    {
      "id": "search",
      "type": "mcp",
      "description": "Search the web using Brave Search",
      "def": {
        "server": "@brave",
        "tool": "brave_web_search"
      }
    }
  ]
}

Best Practices

Use descriptive IDs: Choose clear, kebab-case IDs like web-researcher, not wr
Version control: Commit your capabilities file to git (but never commit actual API keys)
Share with team: Team members can use the same capabilities file for consistent tooling
Use variables: Always use ${VariableName} for credentials, never hardcode them
Start simple: Begin with a few capabilities and expand as needed
List tools in skill requires: Only tools required by at least one skill (or provided by a plugin) are exposed to MCP clients. For MCP tools, use the @server_id.tool_id format (e.g., @brave.search). Command tools use their plain ID.

Companion Files

CAPA may generate two companion files next to your capabilities file:

capabilities.lock: records the exact commit SHA of every remote skill and plugin. Commit it to version control for reproducible installs across machines and CI.
Auto-managed cache: a shared on-disk cache at ~/.capa/cache/ stores cloned snapshots so re-installs are network-free. See capa cache.