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

# 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:

link "my-capability" "provider.toml"

2. Add the name to the DECLARED array:

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

# 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", "[email protected]", "--api-key", "{{ENV:TAVILY_API_KEY}}"]
timeout_seconds = 60
tools = []

Example 2: Deps-only capability (no MCP server)

# 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

# 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