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.
Repo string grammar
Section titled “Repo string grammar”The same @ / :: grammar applies on both GitHub and GitLab (and in capabilities.yaml def.repo fields):
| Form | Meaning |
|---|---|
owner/repo@name | Recursive 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/repo | Exact 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
Section titled “GitHub”GitHub is the default host. No prefix required.
# Search by skill folder namecapa add vercel-labs/agent-skills@web-researcher
# Exact pathcapa add my-org/skills::skills/team-a/web-researcher
# Pin tag or SHAcapa add vercel-labs/agent-skills@web-researcher:v1.2.0capa 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
# Plugincapa add --plugin slackapi/slack-mcp-plugincapa add --plugin anthropics/claude-plugins-official::plugins/frontend-designskills: - id: web-researcher type: github def: repo: vercel-labs/agent-skills@web-researcher description: Web research skill requires: - '@brave.search'
plugins: - id: frontend-design type: github def: repo: anthropics/claude-plugins-official::plugins/frontend-designPrivate GitHub
Section titled “Private GitHub”capa auth github.com --access-token <token>,capa auth github.com(browser OAuth), or Web UI → Integrations → Connect GitHubcapa add my-org/private-skills@team-helpercapa install
Public repos need no token. For GitHub Enterprise, use capa auth <host> --access-token <token> --type github-enterprise.
GitLab
Section titled “GitLab”Prefix CLI sources with gitlab:. Nested groups are supported (any number of path segments before the project).
# Searchcapa add gitlab:mygroup/myrepo@web-researcher
# Nested groupscapa add gitlab:mygroup/subgroup/skills@data-analyst
# Exact pathcapa add gitlab:mygroup/skills::skills/team/web-researcher
# Pincapa add gitlab:mygroup/myrepo@web-researcher:v1.2.0
# Tree URLcapa add https://gitlab.com/mygroup/myrepo/-/tree/main/skills/web-researcher
# Plugincapa add --plugin gitlab:acme/platform/team/services/devops-skills:v1.0.1skills: - id: custom-skill type: gitlab def: repo: mygroup/subgroup/myrepo@skill-name description: Skill from GitLab requires: - '@server1.tool1'In YAML, type: gitlab uses def.repo without the gitlab: CLI prefix (group/project@name).
Self-hosted GitLab
Section titled “Self-hosted GitLab”Prefer a full clone URL when the host is not gitlab.com. CAPA stores it as a type: git source:
capa add https://gitlab.mycompany.com/mygroup/myrepo.gitOr a raw/remote skill URL with type: remote in the capabilities file when you only need a single SKILL.md.
Private GitLab
Section titled “Private GitLab”capa auth gitlab.com --access-token <token>,capa auth gitlab.com(browser OAuth), or Web UI → Integrations → Connect GitLabcapa add gitlab:my-org/private-skills@team-helpercapa install
Self-managed GitLab has no browser OAuth flow; use a personal access token:
capa auth gitlab.mycompany.com --access-token glpat-yourtoken --type gitlab-self-managedcapa add https://gitlab.mycompany.com/mygroup/private-skills.gitAny git host
Section titled “Any git host”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:
capa add https://git.example.com/team/skills.git::skills/review:v1.2.0capa add --plugin ssh://git@git.example.com/team/tools.gitThese 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.
What can come from Git
Section titled “What can come from Git”| Resource | Typical def.repo / CLI |
|---|---|
| Skills | capa add owner/repo@skill |
| Plugins | capa add --plugin owner/repo |
| Rules | Usually owner/repo::path/to/rule.md |
| Agent instructions | Snippets via github / gitlab / local |
| Registries | Adapter sources from git or HTTPS |
Auth commands
Section titled “Auth commands”capa auth # list connected providerscapa auth github.com --access-token <token> # personal access token (recommended)capa auth github.com # browser OAuthcapa auth gitlab.comCAPA 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.