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 seven main sections:

providers:
  - cursor
  - claude-code

options:
  toolExposure: expose-all
  # 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."

skills:
  - id: skill-id
    type: inline|remote|github
    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."
      }
    ]
  },
  "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:

  • cursor - Cursor IDE
  • claude-code - Claude Desktop (Code mode)

2. Options

Configuration for CAPA behavior:

toolExposure

Controls how tools are exposed to the agent:

  • expose-all (default): All tools from all skills are immediately available to the agent. Best for simple setups and clients that support dynamic tool lists.
  • on-demand: Only two meta-tools are exposed: setup_tools and call_tool. The agent must first activate skills with setup_tools, which returns available tool schemas. Then it uses call_tool to invoke any activated tool. This mode reduces context window usage and works with all MCP clients.

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": ""
    }
  }
}

How On-Demand Mode Works

In on-demand mode, the workflow is:

  1. Agent calls: setup_tools({"skills": ["skill-id"]}})
  2. CAPA returns: Full schemas of all tools required by that skill
  3. Agent calls: call_tool({"name": "tool_name", "data": { /* tool args */ }"}"})
  4. CAPA executes: The specified tool and returns results

Benefits of on-demand mode:

  • Minimal context window usage (only 2 tools in system prompt)
  • Works with all MCP clients (no dependency on dynamic tool list updates)
  • Agent receives tool schemas in setup_tools response for reference

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 and/or CLAUDE.md in the project root — the standard files that AI coding agents read for project-specific instructions. Supports a remote base file and a list of snippets sourced from inline text, raw URLs, GitHub, or GitLab. See the Agent Instructions documentation for details.

5. Skills

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

6. Servers

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

7. Tools

Executable capabilities (MCP tools or shell commands). See the Tools 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
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: brave_search
    type: mcp
    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",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}"
        }
      }
    }
  ],
  "tools": [
    {
      "id": "brave_search",
      "type": "mcp",
      "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. Add each tool to the requires array of the skills that use it.

Related Documentation