Skip to content

Git integrations

CAPA fetches remote capabilities from Git hosts: skills, plugins, rules, hooks, and agent instruction snippets. Public repos need no auth. Private repos use capa auth or the Web UI Integrations flow; tokens are stored encrypted in ~/.capa/capa.db.

The same @ / :: grammar applies on both GitHub and GitLab (and in capabilities.yaml def.repo fields):

FormMeaning
owner/repo@nameRecursive search for a basename (skill dir with SKILL.md, or a file basename for rules/snippets). No slashes on the right-hand side.
owner/repo::path/inside/repoExact path from the repo root. No search.

Pinning (both forms):

  • :tag-or-branch, e.g. @skill:v1.2.0, ::rules/git.md:main
  • #sha: commit SHA, e.g. @skill#abc1234

Resolved commits are recorded in capabilities.lock.

GitHub is the default host. No prefix required.

Terminal window
# Search by skill folder name
capa add vercel-labs/agent-skills@web-researcher
# Exact path
capa add my-org/skills::skills/team-a/web-researcher
# Pin tag or SHA
capa add vercel-labs/agent-skills@web-researcher:v1.2.0
capa add vercel-labs/agent-skills@web-researcher#abc1234
# Tree URL (capa parses branch/tag/SHA)
capa add https://github.com/vercel-labs/agent-skills/tree/v1.2.0/skills/web-researcher
# Plugin
capa add --plugin slackapi/slack-mcp-plugin
capa add --plugin anthropics/claude-plugins-official::plugins/frontend-design
  1. capa auth github.com --access-token <token>, capa auth github.com (browser OAuth), or Web UI → Integrations → Connect GitHub
  2. capa add my-org/private-skills@team-helper
  3. capa install

Public repos need no token. For GitHub Enterprise, use capa auth <host> --access-token <token> --type github-enterprise.

Prefix CLI sources with gitlab:. Nested groups are supported (any number of path segments before the project).

Terminal window
# Search
capa add gitlab:mygroup/myrepo@web-researcher
# Nested groups
capa add gitlab:mygroup/subgroup/skills@data-analyst
# Exact path
capa add gitlab:mygroup/skills::skills/team/web-researcher
# Pin
capa add gitlab:mygroup/myrepo@web-researcher:v1.2.0
# Tree URL
capa add https://gitlab.com/mygroup/myrepo/-/tree/main/skills/web-researcher
# Plugin
capa add --plugin gitlab:acme/platform/team/services/devops-skills:v1.0.1

In YAML, type: gitlab uses def.repo without the gitlab: CLI prefix (group/project@name).

Prefer a full clone URL when the host is not gitlab.com. CAPA stores it as a type: git source:

Terminal window
capa add https://gitlab.mycompany.com/mygroup/myrepo.git

Or a raw/remote skill URL with type: remote in the capabilities file when you only need a single SKILL.md.

  1. capa auth gitlab.com --access-token <token>, capa auth gitlab.com (browser OAuth), or Web UI → Integrations → Connect GitLab
  2. capa add gitlab:my-org/private-skills@team-helper
  3. capa install

Self-managed GitLab has no browser OAuth flow; use a personal access token:

Terminal window
capa auth gitlab.mycompany.com --access-token glpat-yourtoken --type gitlab-self-managed
capa add https://gitlab.mycompany.com/mygroup/private-skills.git

Skills and plugins can also come from any repository you can clone (Gitea, Forgejo, self-hosted servers, ssh:// or file:// remotes). Pass a clone URL ending in .git, with optional ::path and :version / #sha suffixes:

Terminal window
capa add https://git.example.com/team/skills.git::skills/review:v1.2.0
capa add --plugin ssh://git@git.example.com/team/tools.git

These are stored as type: git with def.url. Allowed schemes are https, ssh, file, and http only for localhost. Private repos authenticate through your git credential helper or SSH key (a token stored with capa auth for that exact host is also used over HTTPS). user:token@ in a URL is stripped and never written to capabilities.yaml or the lockfile. Unpinned installs take the newest vX.Y.Z tag. See Skills and Plugins.

ResourceTypical def.repo / CLI
Skillscapa add owner/repo@skill
Pluginscapa add --plugin owner/repo
RulesUsually owner/repo::path/to/rule.md
Agent instructionsSnippets via github / gitlab / local
RegistriesAdapter sources from git or HTTPS
Terminal window
capa auth # list connected providers
capa auth github.com --access-token <token> # personal access token (recommended)
capa auth github.com # browser OAuth
capa auth gitlab.com

CAPA hands stored tokens to git without putting them in clone URLs, process arguments, or the cache’s git config. In CI or a cloud sandbox, prefer --access-token; if you use browser OAuth there, add the global --headless flag so CAPA prints the URL instead of opening a browser.

See Credentials and CLI: auth.