Skills CLI

Sync AI skills across all your agent tools with one command

Supports Cursor, Claude Code, Gemini CLI, GitHub Copilot, OpenCode, Windsurf, and more.

Installation • Quick Start • Commands • Supported Tools • Configuration • FAQ

Why Skills CLI?

The problem: You create a skill for Cursor, but need it in Claude Code and Gemini too. Manually copying? Tedious. What if you update it? Copy again to every tool.

The solution: One source of truth. Add once, sync everywhere.

skills source add https://github.com/user/repo/tree/main/skills/react --remote
skills target add cursor
skills target add claude
skills sync  # Done! Skills synced to all targets

What makes it different

| Feature | Description | |---------|-------------| | 🔄 Multi-source | Pull from GitHub, GitLab, Bitbucket, or local folders | | 🎯 Multi-target | Sync to Cursor, Claude, Gemini, Copilot, or any custom directory | | 📂 Subdirectory support | Install specific skills from large mono-repos | | 🏷️ Rename skills | Use --name to avoid conflicts | | 🔍 Diagnostics | doctor command checks your setup | | ⚡ Fast | Built with Bun for maximum performance |

Installation

Prerequisites

• Bun runtime (required - uses Bun shell)
• Git (for remote sources)

Install via Bun

bun install -g @dhruvwill/skills-cli

Install from Source

# Clone the repository
git clone https://github.com/dhruvwill/skills.git
cd skills

# Install dependencies
bun install

# Link globally
bun link

Verify Installation

skills --version
skills doctor

Updating

Update to the latest version with:

skills self-update

Quick Start

# 1. Add a skill from GitHub
skills source add https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices --remote

# 2. Add your targets (path auto-detected for known tools)
skills target add cursor
skills target add claude

# 3. Sync!
skills sync

Check your setup anytime:

skills status   # Overview of skills & targets
skills doctor   # Diagnose issues

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Remote Sources                           │
│   GitHub • GitLab • Bitbucket • Self-hosted Git            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ skills source add
┌─────────────────────────────────────────────────────────────┐
│                    ~/.skills/store/                         │
│                                                             │
│   react-best-practices/    my-custom-skill/    local-skill/ │
│                                                             │
│                   ⬆ Single Source of Truth ⬆                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ skills sync
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│    Cursor     │     │  Claude Code  │     │  Gemini CLI   │
│ ~/.cursor/    │     │ ~/.claude/    │     │ ~/.gemini/    │
│    skills/    │     │    skills/    │     │    skills/    │
└───────────────┘     └───────────────┘     └───────────────┘

Commands

Overview

| Command | Description | |---------|-------------| | skills status | Show overview of skills, targets & sync state | | skills doctor | Diagnose configuration issues | | skills sync | Push skills from store to all targets | | skills update | Refresh all skills from origin | | skills self-update | Update the CLI to the latest version |

Skill Management

| Command | Description | |---------|-------------| | skills source list | List all registered skills | | skills source add <url> --remote | Add a skill from Git repository | | skills source add <path> --local | Add a skill from local folder | | skills source add <url> --remote --name <name> | Add with custom name | | skills source remove <name> | Remove a skill by name |

Target Management

| Command | Description | |---------|-------------| | skills target list | List all targets with sync status | | skills target available | Show predefined targets with paths | | skills target add <name> | Add a predefined target (auto-detects path) | | skills target add <name> <path> | Add a custom target with specific path | | skills target remove <name> | Remove a target |

Supported Tools

Run skills target available to see all supported tools:

| Tool | Path | |------|------| | Cursor | ~/.cursor/skills/ | | Claude Code | ~/.claude/skills/ | | Gemini CLI | ~/.gemini/skills/ | | VS Code / Copilot | ~/.copilot/skills/ | | OpenCode | ~/.config/opencode/skills/ | | Windsurf | ~/.windsurf/skills/ | | Antigravity | ~/.gemini/antigravity/skills/ |

Adding Predefined Targets

# Just use the name - path is auto-detected
skills target add cursor
skills target add claude
skills target add gemini

Adding Custom Targets

# For tools not in the list, specify the path
skills target add mytool ~/path/to/mytool/skills

Adding Skills

From GitHub

# Full repository
skills source add https://github.com/owner/repo --remote

# Specific subdirectory (great for mono-repos)
skills source add https://github.com/owner/repo/tree/main/skills/my-skill --remote

# With custom name (to avoid conflicts)
skills source add https://github.com/owner/repo --remote --name my-custom-name

From GitLab

skills source add https://gitlab.com/owner/repo --remote
skills source add https://gitlab.com/owner/repo/-/tree/main/skills/my-skill --remote

From Bitbucket

skills source add https://bitbucket.org/owner/repo --remote
skills source add https://bitbucket.org/owner/repo/src/main/skills/my-skill --remote

From Local Folder

skills source add ./my-local-skills --local
skills source add /absolute/path/to/skills --local

Configuration

Directory Structure

~/.skills/
├── store/                    # Central repository for all skills
│   ├── react-best-practices/ # Each skill in its own folder
│   │   ├── SKILL.md
│   │   └── rules/
│   └── my-custom-skill/
│       └── SKILL.md
└── config.json               # Registry of sources and targets

Skill Folder Structure

Each skill should follow this structure:

skill-name/
├── SKILL.md          # Main skill definition (required)
├── AGENTS.md         # Agent behavior (optional)
├── rules/            # Additional rules (optional)
│   ├── rule-1.md
│   └── rule-2.md
└── metadata.json     # Skill metadata (optional)

Config File

Located at ~/.skills/config.json:

{
  "sources": [
    {
      "type": "remote",
      "url": "https://github.com/owner/repo/tree/main/skills/my-skill",
      "name": "my-skill"
    },
    {
      "type": "local",
      "path": "/home/user/my-skills",
      "name": "my-local-skill"
    }
  ],
  "targets": [
    {
      "name": "cursor",
      "path": "/home/user/.cursor/skills"
    },
    {
      "name": "claude",
      "path": "/home/user/.claude/skills"
    }
  ]
}

FAQ

How is this different from manually copying files?

Skills CLI provides:

• Single source of truth - Update once, sync everywhere
• Git integration - Pull updates from remote repos with skills update
• Subdirectory support - Install specific skills from large mono-repos
• Status tracking - Know which targets are synced or outdated
• Auto-detection - No need to remember paths for common tools

What happens when I run skills sync?

The contents of ~/.skills/store/ are copied to all registered target directories, maintaining the folder structure:

~/.skills/store/my-skill/  →  ~/.cursor/skills/my-skill/
                           →  ~/.claude/skills/my-skill/
                           →  ~/.gemini/skills/my-skill/

How do I handle naming conflicts?

Use the --name flag when adding skills:

# Two different "utils" skills from different repos
skills source add https://github.com/user1/repo --remote --name user1-utils
skills source add https://github.com/user2/repo --remote --name user2-utils

How do I update skills from remote sources?

skills update  # Pulls latest from all remote sources
skills sync    # Pushes to all targets

Can I add a tool that's not in the predefined list?

Yes! Just specify the path:

skills target add mytool ~/path/to/mytool/skills

Common Issues

"Git is not installed"

Install Git from git-scm.com or via your package manager.

"Skill already exists"

Either remove it first or use --name to give it a different name:

skills source remove old-skill
skills source add <url> --remote

# Or use a different name
skills source add <url> --remote --name new-name

"Unknown target"

The target isn't in the predefined list. Specify the path:

skills target add mytool ~/path/to/skills

Need help?

skills doctor        # Run diagnostics
skills status        # Check current state
skills target available  # See predefined targets
skills --help        # Show all commands

Contributing

git clone https://github.com/dhruvwill/skills.git
cd skills
bun install
bun test

Links

• npm: npmjs.com/package/@dhruvwill/skills-cli
• GitHub: github.com/dhruvwill/skills

License

MIT