add

Use capa add to append an entry without hand-editing YAML. By default it updates the capabilities file. With --passthrough, it writes provider-native files and skips capa management for that add.

Synopsis

capa add [source] [kind flags] [options]

Kind flags (pick one; --skill is assumed when none is set):

capa add [--plugin|--skill|--server|--tool|--rule|--hook] ...

Kind flags

Flag	Description
`--skill`	Treat as a skill (default when no other kind flag is set)
`--plugin`	Treat as a plugin
`--server`	Add an MCP (or future) server entry
`--tool`	Add a tool entry
`--rule`	Add a rule entry
`--hook`	Add a hook entry

Shared options

Flag	Description
`--passthrough`	Write provider-native files; skip the capabilities file and capa management
`--install`	Also run `capa install` after updating the capabilities file
`-e`, `--env [file]`	Load variables from a `.env` file (defaults to `.env`)
`-p`, `--provider <id>`	Provider id for `--install` follow-up, or required for `--passthrough` in non-TTY
`--no-cache`	Bypass the on-disk cache and lockfile when resolving remotes
`--id <id>`	Entry id (required for `--server` / `--tool` / `--hook`; optional override for `--rule`)
`--description <text>`	Optional description

Server options

Use with --server. Provide either stdio (--cmd / --arg) or remote (--url / --header).

Flag	Description
`--type <name>`	Server type (default `mcp`)
`--cmd <bin>`	Stdio command binary
`--arg <token>`	Stdio arg (repeatable)
`--env-var <KEY=VAL>`	Server env var (repeatable)
`--url <url>`	Remote MCP server URL
`--header <KEY=VAL>`	Remote MCP header (repeatable)
`--cwd <path>`	Server working directory

Tool options

Use with --tool.

Flag	Description
`--mcp-server <id>`	MCP server reference (`@id` or `id`)
`--mcp-tool <name>`	Upstream MCP tool name
`--default <KEY=VAL>`	Default arg (repeatable)
`--command <cmd>`	Command tool body
`--group <name>`	Tool group name

Rule options

Use with --rule.

Flag	Description
`--inline <text>`	Inline rule content
`--applies-to <glob>`	`appliesTo` glob (repeatable)
`--always-apply`	Set `alwaysApply`

Hook options

Use with --hook.

Flag	Description
`--type <name>`	Hook type: `command` or `prompt`
`--on <event>`	Hook event (e.g. `sessionStart`, `beforeShell`)
`--command <cmd>`	Shell command body
`--prompt <text>`	Prompt body
`--source <path>`	Alternate body source (path, URL, or repo)
`--matcher <pattern>`	Matcher / pattern
`--timeout <seconds>`	Timeout in seconds
`--fail-closed`	Set `failClosed`
`--sequential`	Set `sequential`

Skill and plugin sources

Without --server / --tool / --rule / --hook, pass a [source]:

Form	Example
GitHub search (`@`)	`capa add owner/repo@skill-name`
GitHub exact (`::`)	`capa add owner/repo::skills/path/to/skill`
Pin tag/branch	`capa add owner/repo@skill:v1.2.3`
Pin commit	`capa add owner/repo@skill#abc1234`
GitLab	`capa add gitlab:group/repo@skill-name`
Registry	`capa add skills-sh:vercel-labs/skills/find-skills`
Remote URL	`capa add https://example.com/path/to/SKILL.md`
Local path	`capa add ./path/to/skill`

Plugins use the same source shapes with --plugin:

capa add --plugin slackapi/slack-mcp-plugin
capa add --plugin anthropics/claude-plugins-official::plugins/frontend-design
capa add --plugin https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review

Examples

# Skill (default kind)
capa add owner/repo@web-researcher
capa add owner/repo@web-researcher --install

# Plugin
capa add --plugin slackapi/slack-mcp-plugin --install

# Passthrough plugin into a provider
capa add --plugin owner/repo@my-plugin --passthrough -p cursor

# Stdio MCP server
capa add --server --id brave --cmd npx --arg -y --arg "@modelcontextprotocol/server-brave-search" \
  --env-var 'BRAVE_API_KEY=${BraveApiKey}'

# Remote MCP server
capa add --server --id remote-api --url https://mcp.example.com/sse \
  --header 'Authorization=Bearer ${Token}'

# MCP tool binding
capa add --tool --id search --mcp-server @brave --mcp-tool brave_web_search

# Rule
capa add --rule --id style --inline "Prefer const over let." --always-apply

# Hook
capa add --hook --id audit-shell --type command --on beforeShell --command "./hooks/audit.sh"