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 four ways to get skills: inline, GitHub, remote URL, and plugins (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"]
      }
    }
  ]
}

Format: owner/repo@skill-name (where skill-name is a subdirectory)

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

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:
        - tool1
        - tool2

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

Best for: Private or custom skills hosted elsewhere.

4. Skills from Plugins

When you add plugins to your capabilities file, their skills are installed automatically when you run capa install. You do not add plugin skills to the skills array by hand; CAPA reads each plugin's manifest and installs its skills alongside your own. Plugin tools are exposed to MCP clients like any other tool.

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:

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

Use the capa add command to quickly add skills:

# Add from GitHub
capa add vercel-labs/agent-skills

# Add specific skill from monorepo
capa add vercel-labs/agent-skills@web-researcher

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

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 (or provided by a plugin) are exposed to MCP clients; tools not in any skill's requires are not available.
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