Skip to content

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.

TypeWhat you provide
inlinedef.content: SKILL.md body in the file
remotedef.url to a SKILL.md
github / gitlabdef.repo with @ or :: grammar
gitdef.url: a clone URL on any git host, plus optional def.path, def.version, def.ref (see Any git host)
localdef.path to a directory that contains SKILL.md (re-read each install)
installedAlready present elsewhere; CAPA only records it for tool binding (edit YAML directly)
pluginSkill shipped by a configured plugin; CAPA does not fetch it again
Terminal window
# GitHub search by basename
capa add owner/repo@skill-name
# Exact path
capa add owner/repo::skills/path/to/skill-name
# GitLab (prefix)
capa add gitlab:group/repo@skill-name
# Pin tag/branch or commit
capa add owner/repo@skill:v1.2.0
capa 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 directory
capa add https://example.com/path/to/SKILL.md
capa add ./path/to/skill
# Registry
capa add skills-sh:vercel-labs/skills/find-skills
FormResolution
owner/repo@basenameRecursive search for a directory whose basename matches (must contain SKILL.md). Basename has no slashes.
owner/repo::exact/pathExact 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'

type: git installs a skill from any repository you can clone: Gitea, Forgejo, a self-hosted server, or a local mirror.

FieldMeaning
def.urlClone URL. https://, ssh://, and file:// work; plain http:// only for localhost
def.pathDirectory inside the repo that holds SKILL.md (default: the repo root)
def.versionTag or branch to pin
def.refCommit SHA to pin
skills:
- id: review
type: git
def:
url: https://git.example.com/team/skills.git
path: skills/review
version: v1.2.0

Without 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.

List the tools the skill needs. MCP tools use @server.tool; command tools use the plain tool id.

def:
requires:
- '@brave.search'
- deploy_service

Under 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.