capa add

Add skills from GitHub, GitLab, Git URLs, local paths, or third-party registries.

Usage

capa add <source> [--plugin | --skill]

Description

Quickly add skills (and plugins, when sourced from a registry or via --plugin) without manually editing the capabilities file. The command resolves the source, writes the resulting entry into your capabilities.yaml or capabilities.json, and then runs capa install automatically.

The id under which the entry is written comes from the source itself — the basename in owner/repo@my-skill, the last subpath segment in owner/repo::skills/my-skill, the directory name for local skills, etc. If the generated id collides with an existing entry, capa add bails out and asks you to rename or remove the existing entry in your capabilities file.

Arguments

<source>

The source of the item to add. CAPA tries each grammar below in order:

  • Registry item: <registryId>:<itemId> (e.g. skills-sh:web-researcher)
  • GitHub (recursive search): owner/repo@skill-name
  • GitHub (exact path): owner/repo::skills/path/to/skill-name
  • GitHub skill URL: https://github.com/owner/repo/tree/main/skills/skill-name
  • GitLab (recursive search): gitlab:group/repo@skill-name (nested groups allowed)
  • GitLab (exact path): gitlab:group/repo::skills/path/to/skill-name
  • GitLab skill URL: https://gitlab.com/group/repo/-/tree/main/skills/skill-name
  • Local path: ./path/to/skill (must contain SKILL.md)
  • Direct URL: https://example.com/path/to/SKILL.md

Pinning to a version or commit. Append :<tag-or-branch> or #<sha> to any GitHub/GitLab source:

# Pin to a tag
capa add owner/repo@skill:v1.2.0

# Pin to a commit SHA (7-40 hex chars)
capa add gitlab:group/repo@skill#abc1234

# Pin an exact-path skill to a tag
capa add owner/repo::skills/data/analyst:v2.0.0

The resolved commit is recorded in capabilities.lock so the next install is reproducible.

When to use @ vs ::

  • @<name> (search): CAPA walks the cloned repo recursively for a directory named <name> containing SKILL.md. The right-hand side is a basename (no slashes). Use this when the skill folder name is unique in the repo and you don't care where it lives.
  • ::<path> (exact): CAPA reads SKILL.md from exactly <path> inside the repo. Use this when two skills share a directory name, when the repo layout matters, or when you want the reference to break loudly if the file moves.

Note: The following prefixes are reserved and never treated as registry IDs, even if you have an adapter with that name: github:, gitlab:, bitbucket:, npm:, file:, http:, https:.

Options

--plugin

Treat <source> as a plugin instead of a skill. See Adding Plugins below for the recognized syntaxes.

--skill

Explicit form of the default behavior. Use this when you want to be unambiguous about the intent (the registry route also honors it as a disagreement guard).

Examples

Add a Skill from a Registry

# Install a skill from skills.sh
capa add skills-sh:web-researcher

# Install a plugin from the Cursor Marketplace
capa add cursor-marketplace:anthropic/claude-helpers

CAPA probes each capability the adapter declares (skills and plugins) and writes the appropriate snippet into your capabilities file. See Registries.

Add a Skill from GitHub

capa add vercel-labs/agent-skills@web-researcher

Add from GitHub with an Exact Path

capa add vercel-labs/agent-skills::skills/web-researcher

Use the :: form when the repo has two skills with the same directory name or when you want the reference to break loudly if the layout changes.

Pin to a Tag or Commit

# Tag / branch
capa add vercel-labs/agent-skills@web-researcher:v1.2.0

# Commit SHA
capa add vercel-labs/agent-skills@web-researcher#abc1234

Add from GitHub Skill URL

capa add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-researcher

Add from GitLab

# Recursive search
capa add gitlab:mygroup/myrepo@my-skill

# Exact path (supports nested groups)
capa add gitlab:mygroup/subgroup/myrepo::skills/team/my-skill

Add from GitLab Skill URL

capa add https://gitlab.com/mygroup/myrepo/-/tree/main/skills/my-skill

Add from a Private Repository

# Connect your provider once via the web UI integrations page, then:
capa add my-org/private-skills@team-helper

CAPA uses your stored GitHub or GitLab OAuth token to clone the private repo. If no token is configured, it prints a clear prompt with the integrations URL.

Add from Local Path

capa add ./my-skills/custom-skill

The local directory must contain a SKILL.md file.

Add from Direct URL

capa add https://example.com/my-skill/SKILL.md

Acknowledge an Externally Installed Skill

If the user installed a skill outside of CAPA (for example, via Cursor's built-in skill manager) and you just want CAPA to bind tools to it, declare it directly in your capabilities file with type: installed:

skills:
  - id: my-external-skill
    type: installed
    def:
      description: Skill installed outside of CAPA
      requires:
        - "@brave.search"
        - some_command_tool

CAPA does not fetch or install type: installed skills; it only records them so tools can bind to them. The same shape works for type: plugin when the skill ships from a configured plugin — see Skills.

How It Works

  1. CAPA decides whether the source is a registry item, a remote repo, a local path, or a URL.
  2. For registries: the adapter's view() function returns an install snippet (skill or plugin), which gets appended to your capabilities file.
  3. For remote repos: CAPA records the source as a github or gitlab skill entry. The actual clone happens during the install step.
  4. CAPA then runs capa install automatically, which resolves the source, writes the lockfile, and installs the skill into your providers.

Skills.sh and the Cursor Marketplace

The skills.sh ecosystem and the Cursor Marketplace both ship as built-in registry adapters in the capa repo. Copy them into ~/.capa/registries/ to browse and install items by ID:

capa add skills-sh:web-researcher
capa add cursor-marketplace:anthropic/claude-helpers

See Registries for full details, including how to write your own adapter for a private company registry.

Adding Plugins

Pass --plugin to add a remote MCP plugin instead of a skill. Plugins follow the same repo grammar as skills — @name for recursive search and ::path for an exact subpath:

# Plugin at the repo root
capa add --plugin slackapi/slack-mcp-plugin

# Recursive search (matches a dir basename or the manifest's "name" field)
capa add --plugin anthropics/claude-code@code-review

# Exact subpath (use when many plugins share a basename)
capa add --plugin anthropics/claude-code::plugins/code-review

# GitLab with nested groups and version pin
capa add --plugin gitlab:acme/platform/devtools@reviewer:v1.2.0

The @ form works for both Claude (.claude-plugin/plugin.json) and Cursor (.cursor-plugin/plugin.json) plugin manifests. Use :: when the plugin's basename collides with another plugin in the same repo.

After Adding a Skill

capa add runs capa install for you. You usually just need to:

  1. Add or wire up any required tools and servers if the skill needs them.
  2. Provide any missing credentials when prompted (see Credentials).
  3. Commit your updated capabilities.{yaml,json} and capabilities.lock.

Related Commands

  • capa install: runs automatically after capa add. You can also run it alone.
  • capa init: initialize a capabilities file.
  • capa registry: inspect available registries.
  • Registries: pluggable third-party registry adapters.
  • Lockfile: how resolved versions and SHAs are recorded.