@rackerlabs/agent-skills-cli

v1.6.0

Published

22 days ago

The open agent skills ecosystem

skills

The CLI for the open agent skills ecosystem.

Introduction

The skills CLI manages AI agent behaviour as code. It installs, updates, and version-locks curated Markdown instruction sets ("skills") into any repository, so every engineer and CI runner gets identical agent context without manual configuration.

What is a Skill?

A skill is a reusable instruction set defined in a SKILL.md file with YAML frontmatter (name and description). Skills let agents perform specialised tasks such as:

Generating release notes from git history
Creating PRs following your team's conventions
Integrating with external tools (Linear, Notion, etc.)

Discover published skills at skills.sh.

Core Capabilities

Reproducible installs: Running skills add twice produces the same result. Skills are symlinked (or copied) into each agent's expected directory and tracked in skills.json.
Version-controlled configuration: skills.json is committed to Git, giving teams a reviewable, diffable record of which skills are active.
Dual distribution: Available as self-contained binaries (for air-gapped environments) or via npx (for standard engineering workflows). See Distribution & Supply Chain Security.

Skill Groups

A skill group is a named collection of related skills that can be installed together. Instead of adding skills individually across every project, architects define groups centrally and teams consume them in a single command:

# Define the group (in the central registry)
skills group add skills-group-coding-data-science python-expert @stable

# Consume it (in any project)
skills install --group skills-group-coding-data-science

Supports OpenCode, Claude Code, Codex, Cursor, and 40 more.

Prerequisites

| Requirement | When Needed | Version | |------------|-------------|--------| | Node.js | When using npx | 20+ | | gh CLI | When cloning from private GitHub repositories | Latest | | cosign | When verifying binary signatures | 2.x |

[!NOTE] When using the standalone binary distribution, Node.js is not required.

Distribution & Supply Chain Security

The skills CLI is distributed in two ways, primarily driven by supply chain security requirements and secondarily by agent startup performance.

1. Verified Binaries (Recommended for CI and Restricted Environments)

Pre-compiled executables for Windows, macOS, and Linux (including ARM64/Graviton). Each release is cryptographically signed via Sigstore (Cosign), allowing you to verify that the binary was built exclusively by the project's GitHub Actions pipeline before granting it execution permissions. Because no runtime resolution occurs at startup, cold-start time is near-instant — critical for ephemeral agent containers where every second of provisioning adds latency.

2. Networked Execution via NPX (Standard Engineering)

For interactive development where convenience outweighs verification, the CLI is published to GitHub Packages. Developers always get the latest version without managing local installations. The trade-off is a short resolution delay on first run and reliance on registry-level trust rather than per-binary signature verification.

🛡 Supply Chain Verification

When downloading binaries in CI or ephemeral containers, you should verify they haven't been tampered with. Every release includes SHA-256 checksums and Sigstore (Cosign) keyless signatures, providing SLSA Level 3 assurance that the binary was built by our GitHub Actions pipeline.

Example: Verifying a binary before use

# 1. Download the binary and its signature bundle
curl -LO https://github.com/rackerlabs/agent-skills-cli/releases/latest/download/skills-linux-x64
curl -LO https://github.com/rackerlabs/agent-skills-cli/releases/latest/download/skills-linux-x64.bundle

# 2. Verify the signature against the release workflow identity
cosign verify-blob skills-linux-x64 \
  --bundle skills-linux-x64.bundle \
  --certificate-identity-regexp "^https://github.com/rackerlabs/agent-skills-cli/.github/workflows/release-binaries.yml" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# 3. Rename, make executable, and run the verified binary
mv skills-linux-x64 skills
chmod +x skills
./skills add owner/repo

Execution Aliases

[!NOTE] Whether you invoke skills (from PATH), execute ./skills-linux-x64 (standalone binary), or run npx @rackerlabs/agent-skills-cli (networked), the behaviour is identical. All usage examples below use the shorthand skills notation.

Quick Start

# Install a skill from a GitHub repository
skills add vercel-labs/agent-skills

# List what's installed
skills list

# Check for updates
skills check

Install a Skill

skills add vercel-labs/agent-skills

Source Formats

# GitHub shorthand (owner/repo)
skills add vercel-labs/agent-skills

# Full GitHub URL
skills add https://github.com/vercel-labs/agent-skills

# Direct path to a skill in a repo
skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# GitLab URL
skills add https://gitlab.com/org/repo

# Any git URL
skills add [email protected]:vercel-labs/agent-skills.git

# Local path
skills add ./my-local-skills

Options

| Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | -g, --global | Install to user directory instead of project | | -a, --agent <agents...> | Target specific agents (e.g., claude-code, codex). See Available Agents | | -s, --skill <skills...> | Install specific skills by name (use '*' for all skills) | | -l, --list | List available skills without installing | | --copy | Copy files instead of symlinking to agent directories | | -y, --yes | Skip all confirmation prompts | | --all | Install all skills to all agents without prompts |

Examples

# List skills in a repository
skills add vercel-labs/agent-skills --list

# Install specific skills
skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator

# Install a skill with spaces in the name (must be quoted)
skills add owner/repo --skill "Convex Best Practices"

# Install to specific agents
skills add vercel-labs/agent-skills -a claude-code -a opencode

# Non-interactive installation (CI/CD friendly)
skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y

# Install all skills from a repo to all agents
skills add vercel-labs/agent-skills --all

# Install all skills to specific agents
skills add vercel-labs/agent-skills --skill '*' -a claude-code

# Install specific skills to all agents
skills add vercel-labs/agent-skills --agent '*' --skill frontend-design

Installation Scope

Scope controls where skills are written to disk — and therefore who else gets them:

1. Project Scope (Default)

What it does: Installs skills into your current project directory (e.g., ./.agents/skills/).
Why use it: The standard workflow. Commit these files to Git so that every engineer cloning the repository inherits the same agent configuration.

2. Global Scope (-g flag)

What it does: Installs skills to your user-level config directory (e.g., ~/.claude-code/skills/).
Why use it: For personal workflow preferences that should apply across all your projects. These are not shared with your team.

| Scope | Flag | Location | Use Case | | ----------- | --------- | ------------------- | --------------------------------------------- | | Project | (default) | ./<agent>/skills/ | Standardized repository integrations (Git) | | Global | -g | ~/<agent>/skills/ | Personal machine-locked developer preferences |

Installation Methods

When installing interactively, you can choose:

| Method | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | | Symlink (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. | | Copy | Creates independent copies for each agent. Use when symlinks aren't supported. |

Managing Skill Groups

A skill group is a named collection of skills that can be installed together. The CLI tracks group definitions in skills.json, which should be committed to Git for version control.

| Command | Description | | ----------------------------------------------------------------------- | -------------------------------------------------- | | skills group create <group-name> | Initialize a new empty skill group | | skills group add <group-name> <source> | Add a skill to a group | | skills group list | View all active skill groups and their nodes | | skills group remove <group-name> <skill-name> | Remove a skill from a group | | skills group delete <group-name> | Delete an entire skill group |

Group Examples

# 1. Create a new skill group
skills group create backend-foundation

# 2. Add skills to the group
skills group add backend-foundation https://github.com/rackerlabs/central-skills-registry/tree/main/python-standards 
skills group add backend-foundation https://github.com/rackerlabs/central-skills-registry/tree/main/docker-security

# 3. List all configured groups
skills group list

# 4. Remove a skill from the group
skills group remove backend-foundation docker-security

# 5. Delete the entire group
skills group delete backend-foundation

Other Commands

| Command | Description | | ---------------------------- | --------------------------------------------------------- | | skills list | List installed skills (alias: ls) | | skills find [query] | Search for skills interactively or by keyword | | skills remove [skills] | Remove installed skills from agents | | skills check | Check for available skill updates | | skills update | Update all installed skills to latest versions | | skills init [name] | Create a new SKILL.md template | | skills verify structure| Validate all skills in skills.json are resolvable (CI use) | | skills verify integrity| Audit local installations against lockfiles for tampering | | skills generate-registry-hashes | Creates a registry-hashes.json cryptographic root of trust |

`skills list`

List all installed skills. Similar to npm ls.

# List all installed skills (project and global)
skills list

# List only global skills
skills ls -g

# Filter by specific agents
skills ls -a claude-code -a cursor

`skills find`

Search for skills interactively or by keyword.

# Interactive search (fzf-style)
skills find

# Search by keyword
skills find typescript

`skills check` / `skills update`

# Check if any installed skills have updates
skills check

# Update all skills to latest versions
skills update

`skills init`

# Create SKILL.md in current directory
skills init

# Create a new skill in a subdirectory
skills init my-skill

`skills remove`

Remove installed skills from agents.

# Remove interactively (select from installed skills)
skills remove

# Remove specific skill by name
skills remove web-design-guidelines

# Remove multiple skills
skills remove frontend-design web-design-guidelines

# Remove from global scope
skills remove --global web-design-guidelines

# Remove from specific agents only
skills remove --agent claude-code cursor my-skill

# Remove all installed skills without confirmation
skills remove --all

# Remove all skills from a specific agent
skills remove --skill '*' -a cursor

# Remove a specific skill from all agents
skills remove my-skill --agent '*'

# Use 'rm' alias
skills rm my-skill

| Option | Description | | -------------- | ------------------------------------------------ | | -g, --global | Remove from global scope (~/) instead of project | | -a, --agent | Remove from specific agents (use '*' for all) | | -s, --skill | Specify skills to remove (use '*' for all) | | -y, --yes | Skip confirmation prompts | | --all | Shorthand for --skill '*' --agent '*' -y |

`skills verify structure`

Validates that every skill referenced in skills.json (both individual skills and skill groups) can be fetched and contains a valid SKILL.md. Designed to run in a central registry's CI pipeline to prevent broken references from being merged.

# Verify all configured skills are structurally resolvable
skills verify structure

`skills verify integrity`

Validates that all locally installed skills in agent configuration folders mathematically match the deterministic hashes captured in your project's skills-lock.json.

It acts as a "secure by default" check: if a developer manually adds an unauthorized un-tracked skill to an agent folder, or someone tampers with the installed files locally to bypass security scopes, this command immediately flags the anomaly and fails the CI environment.

# Verify local environments aren't running unauthorized skills
skills verify integrity

`skills generate-registry-hashes`

Caches deterministic physical file and group hashes from a local directory into a registry-hashes.json artifact. Primarily reserved for Central Skill Registries to establish a cryptographically enforceable Root of Trust.

Supported Agents

Skills can be installed to any of these agents:

| Agent | --agent | Project Path | Global Path | |-------|-----------|--------------|-------------| | Amp, Kimi Code CLI, Replit, Universal | amp, kimi-cli, replit, universal | .agents/skills/ | ~/.config/agents/skills/ | | Antigravity | antigravity | .agents/skills/ | ~/.gemini/antigravity/skills/ | | Augment | augment | .augment/skills/ | ~/.augment/skills/ | | Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ | | OpenClaw | openclaw | skills/ | ~/.openclaw/skills/ | | Cline, Warp | cline, warp | .agents/skills/ | ~/.agents/skills/ | | CodeBuddy | codebuddy | .codebuddy/skills/ | ~/.codebuddy/skills/ | | Codex | codex | .agents/skills/ | ~/.codex/skills/ | | Command Code | command-code | .commandcode/skills/ | ~/.commandcode/skills/ | | Continue | continue | .continue/skills/ | ~/.continue/skills/ | | Cortex Code | cortex | .cortex/skills/ | ~/.snowflake/cortex/skills/ | | Crush | crush | .crush/skills/ | ~/.config/crush/skills/ | | Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ | | Deep Agents | deepagents | .agents/skills/ | ~/.deepagents/agent/skills/ | | Droid | droid | .factory/skills/ | ~/.factory/skills/ | | Firebender | firebender | .agents/skills/ | ~/.firebender/skills/ | | Gemini CLI | gemini-cli | .agents/skills/ | ~/.gemini/skills/ | | GitHub Copilot | github-copilot | .agents/skills/ | ~/.copilot/skills/ | | Goose | goose | .goose/skills/ | ~/.config/goose/skills/ | | Junie | junie | .junie/skills/ | ~/.junie/skills/ | | iFlow CLI | iflow-cli | .iflow/skills/ | ~/.iflow/skills/ | | Kilo Code | kilo | .kilocode/skills/ | ~/.kilocode/skills/ | | Kiro CLI | kiro-cli | .kiro/skills/ | ~/.kiro/skills/ | | Kode | kode | .kode/skills/ | ~/.kode/skills/ | | MCPJam | mcpjam | .mcpjam/skills/ | ~/.mcpjam/skills/ | | Mistral Vibe | mistral-vibe | .vibe/skills/ | ~/.vibe/skills/ | | Mux | mux | .mux/skills/ | ~/.mux/skills/ | | OpenCode | opencode | .agents/skills/ | ~/.config/opencode/skills/ | | OpenHands | openhands | .openhands/skills/ | ~/.openhands/skills/ | | Pi | pi | .pi/skills/ | ~/.pi/agent/skills/ | | Qoder | qoder | .qoder/skills/ | ~/.qoder/skills/ | | Qwen Code | qwen-code | .qwen/skills/ | ~/.qwen/skills/ | | Roo Code | roo | .roo/skills/ | ~/.roo/skills/ | | Trae | trae | .trae/skills/ | ~/.trae/skills/ | | Trae CN | trae-cn | .trae/skills/ | ~/.trae-cn/skills/ | | Windsurf | windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ | | Zencoder | zencoder | .zencoder/skills/ | ~/.zencoder/skills/ | | Neovate | neovate | .neovate/skills/ | ~/.neovate/skills/ | | Pochi | pochi | .pochi/skills/ | ~/.pochi/skills/ | | AdaL | adal | .adal/skills/ | ~/.adal/skills/ |

[!NOTE] Kiro CLI users: After installing skills, manually add them to your custom agent's resources in .kiro/agents/<agent>.json:
{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}

The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.

Creating Skills

Skills are directories containing a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill should be used.

## Steps

1. First, do this
2. Then, do that

Required Fields

name: Unique identifier (lowercase, hyphens allowed)
description: Brief explanation of what the skill does

Optional Fields

metadata.internal: Set to true to hide the skill from normal discovery. Internal skills are only visible and installable when INSTALL_INTERNAL_SKILLS=1 is set. Useful for work-in-progress skills or skills meant only for internal tooling.

---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
  internal: true
---

Skill Discovery

The CLI searches for skills in these locations within a repository:

Root directory (if it contains SKILL.md)
skills/
skills/.curated/
skills/.experimental/
skills/.system/
.agents/skills/
.augment/skills/
.claude/skills/
./skills/
.codebuddy/skills/
.commandcode/skills/
.continue/skills/
.cortex/skills/
.crush/skills/
.factory/skills/
.goose/skills/
.junie/skills/
.iflow/skills/
.kilocode/skills/
.kiro/skills/
.kode/skills/
.mcpjam/skills/
.vibe/skills/
.mux/skills/
.openhands/skills/
.pi/skills/
.qoder/skills/
.qwen/skills/
.roo/skills/
.trae/skills/
.windsurf/skills/
.zencoder/skills/
.neovate/skills/
.pochi/skills/
.adal/skills/

Plugin Manifest Discovery

If .claude-plugin/marketplace.json or .claude-plugin/plugin.json exists, skills declared in those files are also discovered:

// .claude-plugin/marketplace.json
{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "my-plugin",
      "skills": ["./skills/review", "./skills/test"]
    }
  ]
}

This enables compatibility with the Claude Code plugin marketplace ecosystem.

If no skills are found in standard locations, a recursive search is performed.

Compatibility

Skills are generally compatible across agents since they follow a shared Agent Skills specification. However, some features may be agent-specific:

| Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | OpenClaw | Neovate | Pi | Qoder | Zencoder | | --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- | | Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | allowed-tools | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | | context: fork | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | | Hooks | No | No | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No |

Troubleshooting

"No skills found"

Ensure the repository contains valid SKILL.md files with both name and description in the frontmatter.

Skill not loading in agent

Verify the skill was installed to the correct path
Check the agent's documentation for skill loading requirements
Ensure the SKILL.md frontmatter is valid YAML

Permission errors

Ensure you have write access to the target directory.

Environment Variables

| Variable | Description | | ------------------------- | -------------------------------------------------------------------------- | | INSTALL_INTERNAL_SKILLS | Set to 1 or true to show and install skills marked as internal: true | | DISABLE_TELEMETRY | Set to disable anonymous usage telemetry | | DO_NOT_TRACK | Alternative way to disable telemetry |

# Install internal skills
INSTALL_INTERNAL_SKILLS=1 skills add vercel-labs/agent-skills --list

Telemetry

This CLI collects anonymous usage data to help improve the tool. No personal information is collected.

Telemetry is automatically disabled in CI environments.

License

MIT