tap-capability-authoring

## Overview This skill encodes everything needed to create a new capability or dep script in the octomind-tap registry. A capability is the abstraction layer between agents and MCP servers — agents declare what they need, capabilities provide the wiring. This skill covers the full creation checklist: capability file format, provider/symlink pattern, dep script structure, platform coverage requirements, companion documentation, `setup-symlinks.sh` registration, and how to validate everything. Use this skill whenever you need to create a new capability or dep script, or when an agent needs a tool not covered by existing capabilities. ## Instructions ### What Is a Capability? A capability is a named bundle that provides: - Deps — install scripts to run before the session - MCP server config — how to launch the server - Tool permissions — which tools the agent can call Agents declare `capabilities = ["name"]`. At runtime, `bin/load` resolves each name to `capabilities/<name>/default.toml` and merges everything into the final manifest. Key principle: capabilities hide MCP complexity from agents. An agent says "I need websearch" — it doesn't care whether that's Tavily, Brave, or something else. The capability + provider pattern enables swapping implementations without touching agents. ### Capability Directory Structure ``` capabilities/<name>/ <provider-a>.toml ← provider definition (the real file) <provider-b>.toml ← alternative provider (optional) default.toml → <provider-a>.toml (symlink to active provider) ``` - `default.toml` is ALWAYS a symlink — never a real file (except `core` and `agent` which are built-ins) - Users can override the active provider via `[capabilities]` in their config ### Capability File Format ```toml # capabilities/<name>/<provider>.toml # Capability: <name> # Provider: <provider-name> # Title: Short Capability Title (5–60 chars) # Description: What this capability provides (20–160 chars). [deps] require = ["org/tool"] # each entry needs a deps/<org>/<tool>.sh script [roles.mcp] server_refs = ["servername"] # must match a [[mcp.servers]] name below allowed_tools = ["servername:*"] # wildcards OK [[mcp.servers]] name = "servername" type = "stdio" # "stdio", "http", or "builtin" command = "..." # for stdio args = [...] timeout_seconds = 60 tools = [] ``` Not all sections are required: - Deps-only capability (e.g. `programming-python`): only `[deps]` section - MCP-only capability: only `[roles.mcp]` + `[[mcp.servers]]` - Full capability: all three sections Built-in servers (`core`, `octofs`, `agent`, `octocode`) do NOT need `[[mcp.servers]]` blocks. Every other `server_refs` entry MUST have a matching `[[mcp.servers]]` block. Environment variable injection: use `{{ENV:VAR_NAME}}` in capability files for runtime env vars (e.g. API keys). Document required env vars in the capability file header comment. ### Full Creation Checklist When creating a new capability: 1. Create `capabilities/<name>/<provider>.toml` with `# Title:`, `# Description:`, and the appropriate sections 2. Create the dep script at `deps/<org>/<tool>.sh` (if needed) — see dep script format below 3. Create the companion doc at `deps/<org>/<tool>.md` — required for every `.sh` 4. Create the symlink: `cd capabilities/<name> && ln -s <provider>.toml default.toml` 5. Register in `scripts/setup-symlinks.sh`: - Add `link "<name>" "<provider>.toml"` line in the links section - Add `"<name>"` to the `DECLARED` array 6. Run `bash scripts/setup-symlinks.sh` to verify symlinks 7. Run `bash scripts/lint-deps.sh deps/<org>/<tool>.sh` to validate dep script 8. Run `bash scripts/lint-capabilities.sh capabilities/<name>` to validate capability 9. Reference `"<name>"` in the agent's `capabilities = [...]` ### Dep Script Authoring Dep scripts are covered in full by the `tap-deps-authoring` skill. Load it when you need to write or edit a `deps/<org>/<tool>.sh` file: ``` skill(action="use", name="tap-deps-authoring") ``` Key points to know here: - Every `require = ["<org>/<tool>"]` entry in a capability needs a matching `deps/<org>/<tool>.sh` - `type: mcp` — ensures an MCP server runtime is runnable (e.g. `npx`, `uvx`) - `type: dep` — installs a standalone CLI tool used directly - Every `.sh` must have a companion `.md` at the same path ### Companion Documentation Format Every dep script MUST have a matching `.md` file at `deps/<org>/<tool>.md`. For MCP servers (`type: mcp`) — use `templates/dep-mcp.md` as base, must include: - `## MCP Server` — what the server provides - `## Authentication` — required env vars, tokens, setup - `## Available Tools` — list of tools the server exposes - `## Configuration Example` — example capability TOML snippet For plain deps (`type: dep`) — use `templates/dep-tool.md` as base, must include: - `## Key Commands` — most important CLI commands - `## Common Usage` — typical usage patterns ### setup-symlinks.sh Registration When adding a new capability, you MUST update `scripts/setup-symlinks.sh` in two places: 1. Add a `link` call in the links section: ```bash link "my-capability" "provider.toml" ``` 2. Add the name to the `DECLARED` array: ```bash DECLARED=( ...existing entries... "my-capability" ) ``` If you skip either step, `setup-symlinks.sh` will emit a `WARN` for undeclared dirs. Note: `core` and `agent` are built-in capabilities — do NOT add `link` entries for them. They have real files, not symlinks. ## Examples ### Example 1: Simple MCP capability ```toml # capabilities/websearch/tavily.toml # Capability: websearch # Provider: tavily # Title: Web Search via Tavily # Description: Web search and content extraction using the Tavily API. Requires TAVILY_API_KEY. [deps] require = ["tavily/tavily-mcp"] [roles.mcp] server_refs = ["tavily"] allowed_tools = ["tavily:*"] [[mcp.servers]] name = "tavily" type = "stdio" command = "npx" args = ["-y", "tavily-mcp@0.1.14", "--api-key", "{{ENV:TAVILY_API_KEY}}"] timeout_seconds = 60 tools = [] ``` ### Example 2: Deps-only capability (no MCP server) ```toml # capabilities/programming-python/uv.toml # Capability: programming-python # Provider: uv # Title: Python Runtime via uv # Description: Python runtime and package management via uv and uvx. [deps] require = ["astral-sh/uv"] ``` ### Example 3: Capability with HTTP MCP server ```toml # capabilities/octoweb/octoweb.toml # Capability: octoweb # Provider: octoweb # Title: Browser Automation via Octoweb # Description: Browser automation and web scraping via Octoweb HTTP MCP server. [deps] require = ["muvon/octoweb"] [roles.mcp] server_refs = ["octoweb"] allowed_tools = ["octoweb:*"] [[mcp.servers]] name = "octoweb" type = "http" url = "http://localhost:3333" timeout_seconds = 30 tools = [] ``` ## References - `templates/agent.toml` — canonical agent template (for agent creation) - `scripts/setup-symlinks.sh` — symlink management (must update when adding capabilities) - `bash scripts/lint-capabilities.sh` — validates capability files - `bash scripts/setup-symlinks.sh` — creates/refreshes default.toml symlinks - `tap-deps-authoring` skill — full dep script authoring guide