npx skills: install agent skills with the skills CLI
Zihua Li · · 9 min read
One command installs the same agent skill into Claude Code, Codex and Cursor. Here’s what npx skills does with each flag, where the files land and how to check a skill before it runs.
npx skills runs the open-source skills CLI from Vercel Labs, which installs agent skills from GitHub or any Git repository. Run npx skills add owner/repo --skill name in your project, pick your agents with -a, add -g to install for every project, then manage installs with list, check, update and remove.
What npx skills is
skills is an npm package from Vercel Labs: a package manager for agent skills. A skill is a folder with a SKILL.md file in the open Agent Skills format, and most coding agents now read that format, each from its own directory. The CLI’s job is to fetch skills from a repository and put them where each of your agents looks, so one command covers Claude Code, Codex, Cursor and, according to its README, more than 75 other agents.
It needs Node.js 22.20 or later, and nothing to install up front: npx downloads and runs it. Writing npx skills@latest asks npm for the newest release rather than one cached from an earlier run, which is why many READMEs use that form.
Install a skill with npx skills add
Take a real example: ci-audit, a skill that measures where your GitHub Actions time and money go. It lives in heydeer/skills, and a skills repository can hold more than one skill, so start by seeing what’s there:
npx skills@latest add heydeer/skills --list--list prints the skill names and installs nothing. Then install the one you want from your project’s root:
npx skills@latest add heydeer/skills --skill ci-auditInteractively, the CLI asks which agents to install to, offering the ones it detects on your machine, and how: as a symlink to one shared copy, which it recommends, or as independent copies. Before it asks you to confirm, it prints a Security Risk Assessments table for skills from public GitHub repositories, with ratings from Gen, Socket and Snyk and a link to the skill’s page on skills.sh. Then type /ci-audit in Claude Code or Cursor, or $ci-audit in Codex.
The same install without prompts, for a setup script, names everything up front:
npx skills@latest add heydeer/skills --skill ci-audit \
-a claude-code -a codex -a cursor -yFlags for npx skills add
-s, --skillpicks skills by name. Repeat it for several, or pass'*'for all. Quote names with spaces.-a, --agentpicks agents, such asclaude-code,codexorcursor.'*'means every supported agent.-g, --globalinstalls to your home directory instead of the project.--copywrites independent copies instead of symlinks, for systems where symlinks cause trouble.-y, --yesskips confirmations;--allinstalls every skill to every agent without prompts.--rename <name>installs one selected skill under a new name, which changes the folder, the lock entry and thenamein its SKILL.md.
# Several skills from one repository
npx skills add vercel-labs/agent-skills --skill react-best-practices --skill web-design-guidelines
# Every skill in a repository, to specific agents
npx skills add vercel-labs/agent-skills --skill '*' -a claude-code
# Install for every project on this machine
npx skills add anthropics/skills --skill skill-creator -g
# Pin a release tag or commit
npx skills add owner/repo@v1.2.3 --skill my-skill
# Install under another name when two sources clash
npx skills add vercel-labs/json-render --skill shadcn --rename json-render-shadcnPass --skill even when you think a repository holds one skill. Without it, you may install skills you never meant to load, and every installed skill’s description takes room in your agent’s context.
Where the skills CLI puts files
Each agent reads skills from its own folder. The CLI keeps the real files in one place, .agents/skills/<name> for a project install or ~/.agents/skills/<name> for a global one, and links each agent’s folder to it. Agents that already read .agents/skills/ use that copy directly.
| Agent | --agent | Project | Global (-g) |
|---|---|---|---|
| Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ |
| Codex | codex | .agents/skills/ | ~/.agents/skills/ |
| Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ |
So a project install of ci-audit for all three leaves the files in .agents/skills/ci-audit/, which Codex and Cursor read, and a symlink at .claude/skills/ci-audit, which Claude Code follows. Claude Code reads SKILL.md through a symlinked folder and loads the skill once, however many links point at it. How each agent then loads and invokes skills differs; see Codex skills and Cursor skills.
A project install also writes skills-lock.json. It records each skill’s source, the commit it came from and a hash of its files. Commit it with the skills, and teammates and CI can tell whether what’s on disk is what was installed.
Manage skills: list, check, update, remove
The other commands work like a package manager’s:
npx skills list # project skills, with lock status
npx skills ls -g # global skills
npx skills check # updates or local edits? exits 1 if so
npx skills update # update everything
npx skills update ci-audit # update one skill
npx skills remove ci-audit # alias: rm
npx skills find typescript # search the directory
npx skills use vercel-labs/agent-skills@web-design-guidelines --agent claude-codelistcompares project skills with the lock file and marks each onemodifiedif its files changed,untrackedif the lock doesn’t know it, or missing if the lock lists it and the disk doesn’t.checkreports available updates and local edits without changing anything, and exits with code 1 when there are any, so it can fail a CI job.updatetakes-gor-pto limit it to global or project skills, and-yto skip the scope prompt.removetakes-ato remove a skill from some agents only.remove --allremoves only skills the lock file tracks, so skills you wrote by hand are never deleted.usetries a skill without installing it: it prints a prompt built from the skill, or starts the agent you name with it.
skills.sh: the directory and leaderboard
skills.sh is the public face of the CLI. Its leaderboard has three views, All Time, Trending (24h) and Hot, and it’s ranked by anonymous telemetry from the CLI: when someone runs npx skills add on a public GitHub repository, the install counts. There’s no submission form. A skill appears once people install it.
Each listed skill has a page with its install command and source, and the audits page shows results from three scanners side by side: Gen Agent Trust Hub, Socket and Snyk. A repository can show its install count in its README with a badge image from skills.sh/b/owner/repo.
Install counts say a skill is popular, not that it’s good for your codebase. For a shortlist that weighs what skills actually do, see the best Claude Code skills. Telemetry is off when DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 is set, which also turns off the audit lookups during install.
Install agent skills from any GitHub repo
The owner/repo shorthand is the common case, but add takes almost any source:
npx skills add vercel-labs/agent-skills
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
npx skills add https://gitlab.com/org/repo
npx skills add git@github.com:acme/private-skills.git
npx skills add ./my-local-skillsPrivate repositories use the authentication you already have: your Git credential helper, then the GitHub CLI, then SSH. GITHUB_TOKEN or GH_TOKEN can be set for GitHub API access but are optional when Git or gh is already signed in.
Inside a repository, the CLI looks for SKILL.md at the root, in skills/ up to three levels deep, and in the agent folders such as .claude/skills/ and .agents/skills/. It also reads skills declared in a Claude Code plugin manifest, .claude-plugin/marketplace.json or plugin.json, so the skills in a Claude Code plugin repository can be installed through it as plain files too.
Publish your own skill repository
Publishing is pushing a public repository; nothing else to register. npx skills init my-skill creates a template SKILL.md to start from. A layout the CLI finds without configuration:
your-skills/
├── README.md
└── skills/
├── deploy-preview/
│ ├── SKILL.md
│ └── scripts/check.sh
└── release-notes/
└── SKILL.md---
name: release-notes
description: Draft release notes from merged pull requests since the last tag. Use when asked for release notes or a changelog entry.
---
1. Run `git describe --tags --abbrev=0` to find the last tag.
2. List merged pull requests since that tag.
3. Group them as Added, Changed and Fixed, one line each.nameanddescriptionare required, or the CLI reports “No skills found”. Names are lowercase with hyphens.- Write the description for the agent, saying when to use the skill. That text is what the agent matches requests against.
- Set
metadata.internal: trueto hide a work-in-progress skill; it then installs only withINSTALL_INTERNAL_SKILLS=1. - Skills somewhere else, such as
tools/skills/, can be listed in askills.sh.jsonfile at the root with apathsarray.
In your README, give the install command with --skill for each skill and say what the scripts do and need. Tag releases so people can pin with owner/repo@v1.0.0.
Security checks before you install
A skill is instructions your agent follows and scripts that run with your permissions, so treat it like a dependency with shell access. The CLI gives you the tools to check one; using them takes a few minutes.
- Read before you add. Open the skill on GitHub, or run
--listand read the files. Check the SKILL.md for instructions that reach beyond the task, and every script for network calls and credential reads. - Read the risk table. The Gen, Socket and Snyk ratings appear before you confirm. A medium or high rating is a reason to read the details on skills.sh, not to skip them. Repositories that aren’t public on GitHub get no ratings.
- Pin what you depend on. Install from a tag or commit, and commit
skills-lock.json. The lock’s content hash letsnpx skills checkin CI catch a skill whose files changed. - Watch agent-specific fields. In Claude Code, a skill’s
allowed-toolspre-approves tools for the turn that invokes it, and!`command`lines run before the model reads the skill.
npx skills installs SKILL.md folders from any Git repository into Claude Code, Codex, Cursor and other agents with one command. Use --list to see what a repository holds, --skill to take only what you need, -a to choose agents and -g for a machine-wide install, and commit skills-lock.json so updates arrive as reviewable changes.
Committed skills are instructions your whole team’s agents follow, so changes to them deserve the same review as code. HeyDeer, our AI code review agent for GitHub pull requests, leaves approval of any pull request that changes skills, AGENTS.md or CLAUDE.md to a person, and it can follow skills in .agents/skills/ while it runs your repository checks.
Sources
Frequently asked questions
What is npx skills?
npx skills runs the skills package from npm, a CLI from Vercel Labs for the open Agent Skills format. It installs SKILL.md folders from GitHub, GitLab, any Git URL or a local path into the skills directories of Claude Code, Codex, Cursor and dozens of other coding agents, and it needs Node.js 22.20 or later.
How do I install one skill from a repository with many?
To install one skill from a repository with many, pass its name with --skill, as in npx skills add heydeer/skills --skill ci-audit. Run the command with --list first to see the skill names in the repository. Without --skill, the CLI asks which skills to take, and --all installs every one.
Where does npx skills install skills for Claude Code?
For Claude Code, npx skills installs project skills to .claude/skills/<name> and global skills to ~/.claude/skills/<name>. By default it keeps one copy in .agents/skills/ and links each agent’s folder to it; pass --copy to write independent copies instead.
What is the difference between a project and a global install?
A project install, the default, puts skills in the repository, where you can commit them for your team along with skills-lock.json. A global install, with -g, puts them in your home directory, where every project on your machine sees them but nobody else does.
What is skills.sh?
skills.sh is the directory and leaderboard for the skills CLI, run by Vercel. Skills appear on it automatically when people install them with npx skills add, ranked by anonymous install counts, and each listed skill shows security audit results from Gen, Socket and Snyk.
How do I update or remove skills installed with npx skills?
Skills installed with npx skills are updated with npx skills update, or npx skills update <name> for one, and removed with npx skills remove <name>. npx skills check reports available updates and local edits without changing anything, and exits with code 1 when there are any.
Can I turn off npx skills telemetry?
The npx skills CLI sends anonymous install telemetry, which is what ranks the skills.sh leaderboard. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to turn it off; that also turns off the security audit lookups shown before an install.
Is it safe to install skills with npx skills?
Installing skills with npx skills is as safe as the skill you choose. The CLI shows Gen, Socket and Snyk risk ratings for public GitHub skills before you confirm, but a skill’s instructions and scripts still run with your permissions, so read its SKILL.md and scripts before installing.



