Customize Capability

Modify a capability that is already installed in this workspace. The most common request is giving it an MCP server so its agent gains new tools, but the same flow covers adding skills, integrations, or guidance.

A capability's source of truth is its manifest at capabilities/<capability-id>/capability.yaml. Re-installing reads that manifest and upserts the capability, re-install IS the update mechanism, and it never creates a duplicate.

Workflow

1. Identify the capability id from the user's request.
2. Read the current state:
   • If capabilities/<capability-id>/capability.yaml exists, edit it in place.
   • If it does NOT exist (the capability was installed from the catalog), create it. Reconstruct the existing config first so nothing is dropped: keep the capability's current skills (as ref), its integrations, and its agent_prompt, then add your change on top.
3. Apply the change (see "Adding an MCP server" for the common case).
4. Call the capability_install tool with capability_id: <capability-id>. It re-reads the manifest and upserts the capability. A malformed manifest is rejected with a precise error, fix and retry.
5. Tell the user the change takes effect on the next agent run: the runtime compiles MCP servers at run start, so the current run won't see the new tools. Ask them to send a new message to pick them up.

Adding an MCP server

Add an mcp: block to the manifest. Each server connects the capability's agent to an MCP endpoint and exposes the tools you list.

Remote server (an HTTP/SSE MCP endpoint):

mcp:
  servers:
    - id: x                              # letters/digits/_/-, unique in this capability
      type: remote
      url: https://mcp.example/sse
      headers:                           # optional, e.g. auth
        Authorization: Bearer <token>
      tools: [create_post, list_posts]   # which tools to expose (required, ≥1)