What is npx skills?
npx skills runs the skills CLI, Vercel Labs' open source installer for Agent Skills: npx skills add owner/repo copies or links every SKILL.md folder in that repo into the coding agents you choose. The same tool lists, updates and removes skills, and its README describes it as "The CLI for the open agent skills ecosystem."
It supports OpenCode, Claude Code, Codex, Cursor "and 75 more" agents, and the README points you to skills.sh, Vercel's skills directory, to discover skills. The README says it needs Node.js 22.20 or later.
Every command below comes from the README and the official CLI reference, checked against npx skills --help for version 1.7.4 on 28 October 2026. (check is in the README and reference but not in the help text.)
| Command | What it does |
|---|---|
npx skills add <source> |
Install skills from a repo, URL or folder (alias a) |
npx skills find [query] |
Search for skills, interactively or by keyword |
npx skills list |
List installed skills (alias ls) |
npx skills check |
Report available updates without installing them |
npx skills update [skills...] |
Update installed skills (alias upgrade) |
npx skills remove [skills...] |
Remove installed skills (alias rm) |
npx skills use <source>@<skill> |
Use one skill without installing it |
npx skills init [name] |
Create a new SKILL.md template |
npx skills experimental_install |
Restore project skills from skills-lock.json |
npx skills experimental_sync |
Link skills shipped inside npm dependencies |
How do you install a skill with npx skills add?
Run it from your project folder with a source:
npx skills add vercel-labs/agent-skills
With no flags, the CLI shows the skills it found and the agents it detected, asks you to pick, and installs into the current project. The source can take many forms:
# GitHub shorthand
npx skills add vercel-labs/agent-skills
# Full GitHub URL, or a direct path to one skill folder
npx skills add https://github.com/vercel-labs/agent-skills
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# GitLab, Azure Repos, any Git URL
npx skills add https://gitlab.com/org/repo
npx skills add git@github.com:vercel-labs/agent-skills.git
# A folder on your computer
npx skills add ./my-local-skills
Private repositories use the same command. Per the CLI reference, for GitHub sources the CLI tries your normal Git credentials first, then an authenticated GitHub CLI (gh repo clone), then SSH. Setting GITHUB_TOKEN or GH_TOKEN is optional.
You can also point it at a direct download URL for a single SKILL.md or a .zip, .tar, .tar.gz or .tgz archive. Downloads are capped at 10 MiB, extracted content at 25 MiB and archives at 1,000 files by default.
To see what a repo contains without installing anything, add -l:
npx skills add vercel-labs/agent-skills --list
How do you choose agents, scope and single skills?
These flags control what goes where:
| Flag | Meaning |
|---|---|
-g, --global |
Install for your user account, in every project, instead of the current project |
-a, --agent <agents> |
Install only to these agents, such as claude-code or codex; '*' means all |
-s, --skill <skills> |
Install only these skills by name; '*' means all |
-l, --list |
List the skills in the source without installing |
-y, --yes |
Skip confirmation prompts |
--copy |
Copy files instead of symlinking them |
--all |
Shorthand for --skill '*' --agent '*' -y |
--full-depth |
Search every subfolder, even when the repo has a root SKILL.md |
--json |
Print machine-readable results |
Some combinations from the reference:
# One skill, one agent
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code
# Non-interactive, global, for CI
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
# Every skill to every agent
npx skills add vercel-labs/agent-skills --all
Quote skill names that contain spaces, like --skill "Convex Best Practices".
Project or global? Project installs go into each agent's folder in your repo and are meant to be committed and shared with your team. Global installs (-g) go into your home folder and work in every project. The paths for the most common agents, from the CLI's supported agents list:
| Agent | -a name |
Project path | Global path |
|---|---|---|---|
| Claude Code | claude-code |
.claude/skills/ |
~/.claude/skills/ |
| Codex | codex |
.agents/skills/ |
~/.agents/skills/ |
| Cursor | cursor |
.agents/skills/ |
~/.cursor/skills/ |
| Gemini CLI | gemini-cli |
.agents/skills/ |
~/.gemini/skills/ |
| GitHub Copilot | github-copilot |
.agents/skills/ |
~/.copilot/skills/ |
| OpenCode | opencode |
.agents/skills/ |
~/.config/opencode/skills/ |
How do you list, update and remove skills?
List what's installed. It shows project skills by default:
npx skills list # project skills
npx skills ls -g # global skills
npx skills ls -a claude-code -a cursor
Search the directory without leaving the terminal:
npx skills find # interactive search
npx skills find typescript # by keyword
npx skills find react --owner vercel
Check and update. check reports updates without changing anything and, per the reference, "exits with code 1 when any skill has an update, so it can gate CI." update installs them:
npx skills check
npx skills update # everything, asks which scope
npx skills update my-skill # one skill
npx skills update -g # global only (-p for project only)
npx skills update -y # no prompt: project if in a project, else global
Remove skills by name, by source or all at once:
npx skills remove # pick from a list
npx skills remove web-design-guidelines
npx skills remove owner/repo # every skill from that source
npx skills rm --global frontend-design
npx skills remove my-skill --agent '*'
npx skills remove --all # everything, no confirmation
Two more commands are handy. npx skills use vercel-labs/agent-skills@web-design-guidelines prints a prompt built from one skill without installing it, and adding --agent claude-code starts that agent with it. npx skills init my-skill creates my-skill/SKILL.md for you to fill in; our guide to writing a SKILL.md covers what goes inside.
What is skills-lock.json, and should you commit it?
skills-lock.json is the project lock file. The CLI keeps it in your project root to record each project skill and the source it came from, so the same set can be restored later:
npx skills experimental_install
Per the CLI reference, this restores the sources recorded in skills-lock.json into .agents/skills/. It does not install npm packages or create agent-specific links for restored skills. In CI it runs with --frozen-lockfile by default: every restored skill must match the content hash in the lock. A source whose skills differ is skipped, the lock is left untouched, and the command exits with code 1.
Our suggestion: if you want teammates and CI to get the same skills, commit skills-lock.json together with your project's skill folders. Keep in mind that the restore command is marked experimental, and the README warns that experimental commands "may change or be removed in any release without notice."
Global installs are tracked separately. In version 1.7.4 the source code keeps that list in ~/.agents/.skill-lock.json, or under $XDG_STATE_HOME/skills/ when that variable is set. It belongs to your machine, not your repo.
Does npx skills symlink or copy your skills?
By default it symlinks. The CLI reference lists two install methods:
| Method | How it works | When to use it |
|---|---|---|
| Symlink (recommended) | One canonical copy, with a link from each agent's folder to it | Normal use: one source of truth and easy updates |
Copy (--copy) |
A separate copy in each agent's folder | When symlinks aren't supported |
Per the CLI source, the canonical copy sits in .agents/skills/ for a project install or ~/.agents/skills/ for a global one. Agents that already read .agents/skills/ in a project, such as Codex, Cursor and OpenCode, use it directly, while Claude Code gets a link in .claude/skills/. If you edit a symlinked skill, every agent sees the change; with --copy, each copy is on its own.
How do you check a skill before you install it?
A skill is instructions plus scripts that your agent follows, so treat it like any software you install:
- Look before you install. Run
npx skills add <source> --list, then open the repo and readSKILL.mdand every script. - Read the audit results. skills.sh runs automated security audits with Gen, Socket and Snyk. Since
skills@1.4.0,add"clearly displays audit results and risk levels before installation," and skills flagged as malicious are hidden from the skills.sh leaderboard and search. - Heed the warning. Per the CLI source, it prints this reminder after an install: "Review skills before use; they run with full agent permissions."
- Install narrowly. Prefer
--skilland-aover--allfor skills you haven't read, and keep them project-scoped until you trust them.
The CLI sends anonymous telemetry. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to turn off both telemetry and security-audit requests. To find skills worth installing, see the find-skills skill and our list of the best Claude Code skills.
How do you install your own skill library with one command?
The same CLI installs from your own repo, public or private. Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own, and every skill in it installs into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Reading it with the table above: every skill in the repo (--all), into every agent (--all again), for your whole user account (-g), with no prompts. Run npx skills update -g later to pull in changes. For how the format works across tools, see Agent Skills.