GitHub Integration

CAPA makes it easy to add skills from GitHub repositories, enabling you to leverage the skills.sh ecosystem and community-maintained skills.

Adding Skills from GitHub

Using the CLI

The quickest way to add a GitHub skill:

# Add entire repository
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
# Add from specific branch capa add vercel-labs/agent-skills@main

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 the format: owner/repo[@skill-name]

  • owner: GitHub username or organization
  • repo: Repository name
  • skill-name (optional): Subdirectory containing the skill (for monorepos)

Examples

# Single skill repository
vercel-labs/my-skill

# Skill in a monorepo
vercel-labs/agent-skills@web-researcher

# Skill in a subdirectory
myorg/skills@data-analysis/pandas

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

For private repositories, CAPA uses GitHub's authentication. You may need to:

  1. Generate a GitHub Personal Access Token (PAT)
  2. Configure it in your environment or use gh auth login
# Using GitHub CLI
gh auth login

# Using environment variable
export GITHUB_TOKEN=ghp_yourtoken

# Add private skill
capa add myorg/private-skills

Caching and Updates

Skill Caching

CAPA caches downloaded skills locally to speed up installations. Cached skills are stored in:

~/.capa/cache/skills/

Updating Skills

To update skills to the latest version:

# Clear cache and reinstall
rm -rf ~/.capa/cache/skills/
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. Include a comprehensive SKILL.md file
  4. Add a README.md with usage instructions
  5. Tag a release for version tracking

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