Skills
Skills teach agents how to use your tools. You declare them under skills in the capabilities file, then run capa install (or capa add) so CAPA materializes skill folders for each provider.
Skill types
Section titled “Skill types”| Type | What you provide |
|---|---|
inline | def.content: SKILL.md body in the file |
remote | def.url to a SKILL.md |
github / gitlab | def.repo with @ or :: grammar |
git | def.url: a clone URL on any git host, plus optional def.path, def.version, def.ref (see Any git host) |
local | def.path to a directory that contains SKILL.md (re-read each install) |
installed | Already present elsewhere; CAPA only records it for tool binding (edit YAML directly) |
plugin | Skill shipped by a configured plugin; CAPA does not fetch it again |
Add from the CLI
Section titled “Add from the CLI”# GitHub search by basenamecapa add owner/repo@skill-name
# Exact pathcapa add owner/repo::skills/path/to/skill-name
# GitLab (prefix)capa add gitlab:group/repo@skill-name
# Pin tag/branch or commitcapa add owner/repo@skill:v1.2.0capa add owner/repo::skills/x/y#abc1234
# Any git host (clone URL ending in .git)capa add https://git.example.com/team/skills.git::skills/review:v1.2.0
# Remote URL or local directorycapa add https://example.com/path/to/SKILL.mdcapa add ./path/to/skill
# Registrycapa add skills-sh:vercel-labs/skills/find-skills@ vs :: in def.repo
Section titled “@ vs :: in def.repo”| Form | Resolution |
|---|---|
owner/repo@basename | Recursive search for a directory whose basename matches (must contain SKILL.md). Basename has no slashes. |
owner/repo::exact/path | Exact path from the repo root to the skill directory |
Pinning works on both: :tag / :branch or #sha.
skills: - id: find-skills type: github def: repo: vercel-labs/skills@find-skills requires: - '@brave.search'
- id: team-review type: github def: repo: acme/agent-kit::skills/code-review:v1.0.0 requires: - '@gitlab.list_merge_requests'Any git host
Section titled “Any git host”type: git installs a skill from any repository you can clone: Gitea, Forgejo, a self-hosted server, or a local mirror.
| Field | Meaning |
|---|---|
def.url | Clone URL. https://, ssh://, and file:// work; plain http:// only for localhost |
def.path | Directory inside the repo that holds SKILL.md (default: the repo root) |
def.version | Tag or branch to pin |
def.ref | Commit SHA to pin |
skills: - id: review type: git def: url: https://git.example.com/team/skills.git path: skills/review version: v1.2.0Without version or ref, CAPA installs the newest vX.Y.Z tag (or the default branch when the repo has no version tags). The resolved commit is pinned in the lockfile like any other git source.
Private repos authenticate through your own git setup: the git credential helper for HTTPS, or your SSH key for ssh://. (A token you stored for that exact host with capa auth is used over HTTPS too.) If a clone fails with an auth error, run git clone <url> once so git remembers the credentials, then install again. Don’t put credentials in the URL: capa add strips user:token@ before writing capabilities.yaml, and CAPA never uses them for the clone or writes them to capabilities.lock.
Bind tools with requires
Section titled “Bind tools with requires”List the tools the skill needs. MCP tools use @server.tool; command tools use the plain tool id.
def: requires: - '@brave.search' - deploy_serviceUnder on-demand tool exposure, skills without requires get no tools activated. Prefer setting requires on every skill you care about.
Under search (the default for new projects), requires has no effect: the agent can search every tool in the project, and the Web UI hides skill wiring on tools. Tools a server exposes through its expose policy never need a requires entry.