GitHub Integration

CAPA pulls skills directly from GitHub repositories, including the skills.sh ecosystem and any community-maintained collection.

Adding Skills from GitHub

Using the CLI

The quickest way to add a GitHub skill:

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

# Add at an exact path inside the repo (use when names collide)
capa add my-org/skills::skills/team-a/web-researcher

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

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

# Add from a GitHub skill URL (CAPA parses the branch/tag/SHA)
capa add https://github.com/vercel-labs/agent-skills/tree/v1.2.0/skills/web-researcher

Manual Configuration

Add GitHub skills directly in your capabilities file:

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

Repository Format

GitHub skills use one of two grammars:

  • 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.
  • owner/repo::<path> (exact path): CAPA reads SKILL.md from exactly <path> inside the repo.

Each grammar accepts an optional :<tag-or-branch> suffix or #<sha> suffix for version pinning.

Examples

# Skill in a monorepo (search by directory name)
vercel-labs/agent-skills@web-researcher

# Skill at an exact path inside the repo
my-org/skills::skills/data/analyst

# Pin to a tag
vercel-labs/agent-skills@web-researcher:v1.2.0

# Pin to a commit SHA (7-40 hex chars)
vercel-labs/agent-skills@web-researcher#abc1234

# Pin an exact-path skill to a tag
my-org/skills::skills/data/analyst:v2.0.0

Skill Repository Structure

A GitHub repository can contain a single skill or multiple skills (monorepo):

Single Skill Repository

my-skill/
├── SKILL.md
└── README.md (optional)

Monorepo with Multiple Skills

agent-skills/
├── web-researcher/
│   └── SKILL.md
├── data-analyst/
│   └── SKILL.md
└── code-reviewer/
    └── SKILL.md

Skills.sh Ecosystem

The skills.sh ecosystem provides a standardized format for AI agent skills.

Popular Skill Repositories

  • vercel-labs/agent-skills - Official collection of agent skills
  • Community-contributed skills on GitHub with the skills-sh topic

Finding Skills

Search for skills on GitHub:

  • Search for repositories with the skills-sh topic
  • Browse the skills.sh directory
  • Check community collections and curated lists

Authentication

Public Repositories

No authentication required for public repositories.

Private Repositories (Recommended: OAuth via CAPA)

The simplest way to install from a private GitHub repo is to connect your account through the CAPA web UI:

  1. Start the server: capa start
  2. Open the web UI and navigate to the Integrations page.
  3. Click Connect GitHub and complete the OAuth flow.
  4. Run capa add my-org/private-skills@team-helper. CAPA uses your stored token to clone the repo.

If you try to add a private repo without a token, CAPA prints a clear error with the integrations URL so you can connect and retry.

Private Repositories (Alternative: gh CLI)

If you'd rather use a personal access token managed by the GitHub CLI:

gh auth login
capa add my-org/private-skills@team-helper

Caching, Lockfile, and Updates

How Caching Works

On every install, CAPA clones the requested repo into ~/.capa/cache/ as a bare mirror, then materialises a snapshot for the resolved commit. Subsequent installs that reference the same commit reuse the snapshot directly. No network call required.

# Inspect what's cached
capa cache

# Wipe the entire cache
capa cache clean

Reproducible Installs

The resolved commit SHA for each remote skill is recorded in capabilities.lock. Commit this file to version control so teammates and CI install the exact same code.

Updating Skills

To pull the latest commit on an unpinned source, bypass the lockfile and cache for one run:

capa install --no-cache

To upgrade a pinned skill, bump its version (or the suffix after : or # in the repo string) in your capabilities file and re-run capa install.

Creating Your Own Skills

Skill Repository Template

Create a GitHub repository with a SKILL.md file:

---
name: my-custom-skill
description: Brief description of the skill
---

# My Custom Skill

Detailed description of what this skill does and how to use it.

## When to Use

- Situation 1
- Situation 2

## Required Tools

- tool_1
- tool_2

## Examples

Example usage scenarios.

Publishing to skills.sh

  1. Create a GitHub repository with your skill.
  2. Add the skills-sh topic to your repository.
  3. Write a clear SKILL.md file with the frontmatter the format requires.
  4. Add a README.md with usage instructions.
  5. Tag a release so users can pin to a version.

Best Practices

  • Review before adding: Always review skills from public repositories before adding them
  • Pin versions: Use specific commits or tags for production deployments
  • Document dependencies: Clearly specify required tools in the skill's requires array
  • Keep skills focused: Each skill should have a single, clear purpose
  • Version your skills: Use semantic versioning and git tags

Examples

Adding a Web Research Skill

# Add the skill
capa add vercel-labs/agent-skills@web-researcher

# This adds to your capabilities file:
# skills:
#   - id: web-researcher
#     type: github
#     def:
#       repo: vercel-labs/agent-skills@web-researcher

# Then add required tools and install
capa install

Complete Example with GitHub Skill

providers:
  - cursor

skills:
  - id: web-researcher
    type: github
    def:
      repo: vercel-labs/agent-skills@web-researcher
      requires:
        - brave_search

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: brave_search
    type: mcp
    def:
      server: "@brave"
      tool: brave_web_search

Troubleshooting

Skill Not Found

  • Verify the repository exists and is public (or you have access)
  • Check the skill path is correct (for monorepos)
  • Ensure the repository contains a SKILL.md file

Authentication Failed

  • Check your GitHub token has the required permissions
  • Verify the token is not expired
  • Try gh auth login to refresh authentication

Skill Content Invalid

  • Ensure SKILL.md has valid frontmatter
  • Check the skill follows the skills.sh format
  • Review CAPA logs for specific parsing errors

Related Documentation