Quickstart

Install your first skill in under 2 minutes

This guide will walk you through installing and using your first agent skill.

Install a Skill

The quickest way to get started is to install skills from a GitHub repository:

Terminal

npx skills add vercel-labs/agent-skills

1. Source Detection

   The CLI parses the source and clones the repository

2. Skill Discovery

   Automatically discovers all skills in the repository

3. Agent Detection

   Detects which coding agents you have installed

4. Interactive Selection

   Select which skills and agents to install to

5. Installation

   Installs skills with your chosen method (symlink or copy)

List Available Skills

Before installing, you can preview available skills in a repository:

Terminal

npx skills add vercel-labs/agent-skills --list

This shows all skills without installing anything.

Source Formats

The CLI supports multiple source formats:

GitHub Shorthand

# owner/repo format
npx skills add vercel-labs/agent-skills

# Complete repository URL
npx skills add https://github.com/vercel-labs/agent-skills

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

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

# Any git URL
npx skills add [e-mail]:vercel-labs/agent-skills.git

# Local directory
npx skills add ./my-local-skills

Installation Options

Install to Specific Agents

Target specific coding agents using the --agent or -a flag:

Terminal

# Install to Claude Code and Cursor
npx skills add vercel-labs/agent-skills -a claude-code -a cursor

# Install to all detected agents
npx skills add vercel-labs/agent-skills -a '*'

Available agent names: claude-code, codex, cursor, cline, opencode, windsurf, and 37 more.

Install Specific Skills

Install only certain skills from a repository:

Terminal

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

# Skill names with spaces must be quoted
npx skills add owner/repo --skill "Convex Best Practices"

# Install all skills from repo
npx skills add vercel-labs/agent-skills --skill '*'

Global vs Project Installation

By default, skills are installed at the project level. Use -g for global installation:

Project (Default)

# Installs to ./<agent>/skills/
# Shared with team when committed
npx skills add vercel-labs/agent-skills

# Installs to ~/<agent>/skills/
# Available across all projects
npx skills add vercel-labs/agent-skills -g

Scope	Flag	Location	Use Case
Project	(default)	./<agent>/skills/	Committed with your project, shared with team
Global	-g	~/<agent>/skills/	Available across all projects

Installation Methods

When installing interactively, you can choose between:

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.

To force copy mode non-interactively:

Terminal

npx skills add vercel-labs/agent-skills --copy

Non-Interactive Installation

For CI/CD pipelines or automation, skip all prompts:

Terminal

# Skip all confirmation prompts
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y

# Install all skills to all agents without prompts
npx skills add vercel-labs/agent-skills --all

The --all flag is shorthand for --skill '*' --agent '*' -y

Managing Skills

List Installed Skills

View all installed skills:

Terminal

# List project skills
npx skills list

# List global skills
npx skills ls -g

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

Search for Skills

Find skills interactively or by keyword:

Terminal

# Interactive search (fzf-style)
npx skills find

# Search by keyword
npx skills find typescript

Check for Updates

Check if any installed skills have updates:

Terminal

npx skills check

The CLI compares the GitHub tree SHA of your installed skills against the latest version in the repository.

Update checking only works for skills installed from GitHub repositories. Local paths and git URLs are skipped.

Update Skills

Update all skills to their latest versions:

Terminal

npx skills update

This automatically reinstalls each skill that has an available update.

Remove Skills

Remove installed skills:

Terminal

# Interactive selection
npx skills remove

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

# Remove multiple skills
npx skills remove skill1 skill2 -y

# Remove from global scope
npx skills remove --global my-skill

# Remove from specific agents
npx skills rm --agent claude-code my-skill

# Remove all skills
npx skills remove --all

Creating Your Own Skills

Initialize a Skill

Create a new skill template:

Terminal

# Create SKILL.md in current directory
npx skills init

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

This creates a SKILL.md file with the required frontmatter:

SKILL.md

---
name: my-skill
description: A brief description of what this skill does
---

# my-skill

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

## When to use

Describe when this skill should be used.

## Instructions

1. First step
2. Second step
3. Additional steps as needed

Skill Structure

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

Required Fields

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

# My Skill

Instructions for the agent...

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

# Internal Skill

This skill is hidden from normal discovery.

Required Fields

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

Publishing Your Skill

Once you’ve created a skill:

1. Create Repository

   Push your skill to GitHub in a repository

2. Organize Skills

   Place skills in a skills/ directory (recommended) or root

3. Share

   Others can install with npx skills add owner/repo

4. Submit to Registry

   Submit to skills.sh for discovery

Advanced Features

Restore from Lock File

Restore skills from skills-lock.json (experimental):

Terminal

npx skills experimental_install

Sync from node_modules

Sync skills found in node_modules (experimental):

Terminal

# Interactive sync
npx skills experimental_sync

# Non-interactive sync
npx skills experimental_sync -y

# Sync to specific agents
npx skills experimental_sync -a claude-code -a cursor

Common Workflows

Team Collaboration

Share skills with your team by installing at project level:

Terminal

# Install to project
npx skills add vercel-labs/agent-skills --skill pr-review

# Commit the skills directory
git add .claude/skills/
git commit -m "Add PR review skill"

Team members will have the skills when they clone the repository.

Personal Productivity

Install skills globally for personal use across all projects:

Terminal

# Install globally
npx skills add vercel-labs/agent-skills -g --skill release-notes

# Available in all projects now

CI/CD Integration

Use non-interactive mode in CI pipelines:

Terminal

# Install specific skills for CI
DISABLE_TELEMETRY=1 npx skills add owner/repo \
  --skill "code-review" \
  -a claude-code \
  -y

Example Commands

Basic Install

# Install from GitHub shorthand
npx skills add vercel-labs/agent-skills

# Install globally
npx skills add vercel-labs/agent-skills -g

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

# Install specific skills
npx skills add vercel-labs/agent-skills --skill pr-review --skill commit

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

# Install all skills to all agents
npx skills add vercel-labs/agent-skills --all

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 using npx skills list
• Check the agent’s documentation for skill loading requirements
• Ensure the SKILL.md frontmatter is valid YAML
• Restart your coding agent to reload skills

Permission errors

Ensure you have write access to the target directory. Try using global installation (-g) or check directory permissions.

Rate limit errors

If you hit GitHub API rate limits:

Terminal

# Set a GitHub token for higher limits
export GITHUB_TOKEN=ghp_your_token_here
npx skills add vercel-labs/agent-skills

Next Steps

Browse Skills

Discover community skills at skills.sh

Agent Skills Spec

Learn about the Agent Skills specification

Create a Skill

Build your own skill with npx skills init

View Source

Explore the CLI source code