Skills

Skills are modular knowledge packages that teach AI agents when and how to use tools. They're non-executable markdown documentation that provides context to the agent.

Skills vs Tools

Skills: Provide knowledge and context (markdown files with instructions)
Tools: Perform actual operations (executable capabilities)

Think of skills as the "manual" and tools as the "functions" the agent can call.

Skill Types

CAPA supports seven ways to define skills: inline, GitHub, GitLab, remote URL, local path, installed, and plugin (see below).

1. Inline Skills

Embed the skill content directly in your capabilities file:

skills:
  - id: web-researcher
    type: inline
    def:
      description: Web research skill
      requires:
        - '@brave.search'
      content: |
        ---
        name: web-researcher
        description: Search the web for information
        ---
        
        # Web Researcher
        
        Use the brave.search tool to find current information online.
        
        ## When to Use
        - User asks for current information
        - Need to verify facts
        - Research topics

{
  "skills": [
    {
      "id": "web-researcher",
      "type": "inline",
      "def": {
        "description": "Web research skill",
        "requires": ["@brave.search"],
        "content": "---\nname: web-researcher\ndescription: Search the web for information\n---\n\n# Web Researcher\n\nUse the brave.search tool to find current information online."
      }
    }
  ]
}

Best for: Project-specific skills unique to your workflow.

2. GitHub Skills

Fetch skills from GitHub repositories (skills.sh ecosystem):

skills:
  - id: web-researcher
    type: github
    def:
      repo: vercel-labs/agent-skills@web-researcher
      description: Web research skill from skills.sh
      requires:
        - '@brave.search'

{
  "skills": [
    {
      "id": "web-researcher",
      "type": "github",
      "def": {
        "repo": "vercel-labs/agent-skills@web-researcher",
        "description": "Web research skill from skills.sh",
        "requires": ["@brave.search"]
      }
    }
  ]
}

Repo string formats. CAPA supports two grammars for the right-hand side of the repo string:

owner/repo@<name> (recursive search): CAPA walks the cloned repo 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 within the repo.
owner/repo::<path> (exact path): 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.

Pinning a version or commit. Both grammars accept an optional :<tag-or-branch> suffix or #<sha> suffix:

skills:
  # Pinned to a tag (search form)
  - id: web-researcher
    type: github
    def:
      repo: vercel-labs/agent-skills@web-researcher:v1.2.0

  # Pinned to a commit (exact-path form)
  - id: data-analyst
    type: github
    def:
      repo: my-org/skills::skills/data/analyst#abc1234def

  # Skills can also use top-level version/ref fields
  - id: code-reviewer
    type: github
    def:
      repo: my-org/skills@code-reviewer
      version: v2.0.0

{
  "skills": [
    {
      "id": "web-researcher",
      "type": "github",
      "def": { "repo": "vercel-labs/agent-skills@web-researcher:v1.2.0" }
    },
    {
      "id": "data-analyst",
      "type": "github",
      "def": { "repo": "my-org/skills::skills/data/analyst#abc1234def" }
    },
    {
      "id": "code-reviewer",
      "type": "github",
      "def": {
        "repo": "my-org/skills@code-reviewer",
        "version": "v2.0.0"
      }
    }
  ]
}

The resolved commit SHA is recorded in capabilities.lock so future installs use the same code until you intentionally bump the version.

Best for: Well-maintained community skills from the skills.sh ecosystem and from internal monorepos.

3. Remote Skills

Fetch skill content from any URL:

skills:
  - id: custom-skill
    type: remote
    def:
      url: https://example.com/my-skill/SKILL.md
      description: Custom remote skill
      requires:
        - '@server1.tool1'

{
  "skills": [
    {
      "id": "custom-skill",
      "type": "remote",
      "def": {
        "url": "https://example.com/my-skill/SKILL.md",
        "description": "Custom remote skill",
        "requires": ["@server1.tool1"]
      }
    }
  ]
}

Best for: Private or custom skills hosted elsewhere.

4. Local Skills

Reference a skill directory on the local filesystem:

skills:
  - id: my-local-skill
    type: local
    def:
      path: ./my-skills/custom-skill
      description: Local skill from project directory
      requires:
        - '@server1.tool1'

{
  "skills": [
    {
      "id": "my-local-skill",
      "type": "local",
      "def": {
        "path": "./my-skills/custom-skill",
        "description": "Local skill from project directory",
        "requires": ["@server1.tool1"]
      }
    }
  ]
}

Best for: Project-local skills you edit in the repo, or shared skills in a monorepo subdirectory.

5. Installed Skills

Acknowledge a skill that the user installed outside of CAPA (for example, via Cursor's skill system or another tool). CAPA does not install or fetch anything. It only records the skill's existence so tools can be tied to it via requires.

skills:
  - id: my-installed-skill
    type: installed
    def:
      description: Skill installed by user outside capa
      requires:
        - '@server.tool1'
        - tool2

{
  "skills": [
    {
      "id": "my-installed-skill",
      "type": "installed",
      "def": {
        "description": "Skill installed by user outside capa",
        "requires": ["@server.tool1", "tool2"]
      }
    }
  ]
}

Best for: Skills already installed by the user; use when you want CAPA to expose tools for that skill without managing its installation.

CLI: capa add <skill-id> --installed [--requires "@server.tool1,tool2"] [-d "description"]

6. Plugin Skills

Bind a skill that lives inside a plugin to a set of tools you've declared. The plugin copies its SKILL.md onto disk automatically (so the MCP client can read it), but capa won't auto-expose any plugin tools — you control that with this entry plus your tools declarations.

skills:
  - id: slack-messaging   # must match a skill id from a configured plugin
    type: plugin
    def:
      description: Post messages to Slack channels
      requires:
        - '@slack.send_message'  # qualified id of a tool you declared

{
  "skills": [
    {
      "id": "slack-messaging",
      "type": "plugin",
      "def": {
        "description": "Post messages to Slack channels",
        "requires": ["@slack.send_message"]
      }
    }
  ]
}

Plugin skills behave like installed skills — capa never fetches or installs content for these entries; the plugin itself handles installation when it's resolved. If a type: plugin skill id doesn't match any skill exposed by your configured plugins, capa install emits a warning so you can catch typos or stale references.

Best for: Activating skills shipped by a plugin without surrendering control of which tools the agent can call.

You don't have to declare every plugin skill by hand. Skills that the plugin contributes but you didn't list in your capabilities still appear in capabilities.skills as type: plugin with plugin attribution — they just have no requires bindings. Declare a matching type: plugin entry whenever you want to attach tools to one of them.

Skill Structure

Skills use the SKILL.md format with frontmatter:

---
name: skill-name
description: Brief description of what this skill does
---

# Skill Title

Detailed description and instructions for the agent.

## When to Use

- Situation 1
- Situation 2

## How to Use

Instructions on using the associated tools.

## Examples

Example usage scenarios.

The requires Field

The requires array specifies which tools this skill needs. MCP tools use the @server_id.tool_id format; command tools use their plain ID:

skills:
  - id: web-researcher
    type: inline
    def:
      requires:
        - '@brave.search'
        - web_scrape
      content: |
        # Content here

{
  "skills": [
    {
      "id": "web-researcher",
      "type": "inline",
      "def": {
        "requires": ["@brave.search", "web_scrape"],
        "content": "# Content here"
      }
    }
  ]
}

The behavior depends on your toolExposure setting:

expose-all mode: All tools from all skills are immediately available to the agent.
on-demand mode: When calling setup_tools({"skills": ["web-researcher"]}}), CAPA returns the schemas for brave.search and web_scrape. The agent then uses call_tool to invoke them.

Adding Skills from GitHub or Registries

Use the capa add command to quickly add skills:

# Add a skill from GitHub (recursive search by directory name)
capa add vercel-labs/agent-skills@web-researcher

# Add a skill from GitHub at an exact path
capa add my-org/skills::skills/data/analyst

# Pin to a tag or commit
capa add vercel-labs/agent-skills@web-researcher:v1.2.0
capa add my-org/skills@team-helper#abc1234

# Install from a third-party registry (see Registries docs)
capa add skills-sh:web-researcher

# Add with custom ID
capa add vercel-labs/agent-skills@web-researcher --id my-skill

See the capa add reference and Registries for the full set of source formats.

Best Practices

Keep skills focused: Each skill should have a single, clear purpose
Document thoroughly: Provide clear instructions on when and how to use tools
Include examples: Show the agent concrete usage scenarios
Specify requirements: Always list required tools in the requires array. Only tools that are required by at least one skill are exposed to MCP clients; tools not in any skill's requires are not available. This rule applies uniformly to user-defined tools and to tools that proxy plugin servers.
Use descriptive IDs: Choose clear, kebab-case IDs like web-researcher

Skills.sh Ecosystem

The skills.sh ecosystem provides a collection of community-maintained skills. Popular repositories include:

vercel-labs/agent-skills - Official collection of agent skills
Many community-contributed skills on GitHub