customize-capability

# 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): ```yaml 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) ``` Local server (a subprocess speaking MCP over stdio): ```yaml mcp: servers: - id: helper type: local command: [npx, "-y", "@modelcontextprotocol/server-everything"] environment: # optional SOME_TOKEN: "{env:SOME_TOKEN}" # reads from the runtime environment tools: [echo, add] ``` Rules: - `tools` must list at least one tool name — you declare exactly which tools to expose. - Remote servers require `url`; local servers require `command`. - Put auth in `headers` (remote) or `environment` (local). Both header and environment values may use `{env:VAR_NAME}` to read from the runtime environment instead of hard-coding secrets. - Ask the user for the server url/command, which tools to expose, and any auth before writing the manifest. The exposed tools become available to the capability's agent on the next run. ## After installing Confirm what you changed and remind the user to start a new message so the agent picks up the new MCP tools.