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:
npx skills add vercel-labs/agent-skills
Source Detection
The CLI parses the source and clones the repository
Skill Discovery
Automatically discovers all skills in the repository
Agent Detection
Detects which coding agents you have installed
Interactive Selection
Select which skills and agents to install to
Installation
Installs skills with your chosen method (symlink or copy)
List Available Skills Before installing, you can preview available skills in a repository:
npx skills add vercel-labs/agent-skills --list
This shows all skills without installing anything.
The CLI supports multiple source formats:
GitHub Shorthand
Full GitHub URL
Specific Skill Path
GitLab URL
Git URL
Local Path
# owner/repo format npx skills add vercel-labs/agent-skills
Installation Options Install to Specific Agents Target specific coding agents using the --agent or -a flag:
# 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:
# 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:
# Installs to ./<agent>/skills/ # Shared with team when committed npx skills add vercel-labs/agent-skills
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:
npx skills add vercel-labs/agent-skills --copy
Non-Interactive Installation For CI/CD pipelines or automation, skip all prompts:
# 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:
# 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:
# Interactive search (fzf-style) npx skills find # Search by keyword npx skills find typescript
Check for Updates Check if any installed skills have updates:
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:
This automatically reinstalls each skill that has an available update.
Remove Skills Remove installed skills:
# 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:
# 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:
--- 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
Optional Fields
--- name : my-skill description : What this skill does and when to use it --- # My Skill Instructions for the agent...
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:
Create Repository
Push your skill to GitHub in a repository
Organize Skills
Place skills in a skills/ directory (recommended) or root
Share
Others can install with npx skills add owner/repo
Advanced Features Restore from Lock File Restore skills from skills-lock.json (experimental):
npx skills experimental_install
Sync from node_modules Sync skills found in node_modules (experimental):
# 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:
# 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:
# 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:
# Install specific skills for CI DISABLE_TELEMETRY = 1 npx skills add owner/repo \ --skill "code-review" \ -a claude-code \ -y
Example Commands Basic Install
Global Install
Specific Agents
Specific Skills
Non-Interactive
Install All
# Install from GitHub shorthand npx skills add vercel-labs/agent-skills
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:
# 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
