npx skills: The Agent Skills CLI Every Command, and What It Does to Your Machine

Key Takeaways

• npx skills runs the npm package skills, from vercel-labs/skills. It is MIT-licensed and needs Node.js 22.20 or later.
• The part after @ is the skill's frontmatter name:, not its folder. When the two differ, the folder name fails with “No matching skills found”.
• A project install writes one copy to .agents/skills/ and links each agent to it. For Claude Code, that link is .claude/skills/<name>.
• npx skills check is not a dry run. In the source it is another name for update, and it updates.
• Nothing in a skill runs at install time — but nothing shows you the SKILL.md either. The CLI's own closing line is “Review skills before use; they run with full agent permissions.”

What Is npx skills?

npx skills is the command-line installer for agent skills — folders built around a SKILL.md file that tell an agent how to do one job. npx downloads the npm package skills and runs it, so there is nothing to install first. The package is published from vercel-labs/skills on GitHub under the MIT licence; at the time of writing the current version is 1.7.0, and it declares node >=22.20.0. On an older Node, npm warns with EBADENGINE.

One CLI covers many agents. Its README lists Claude Code, Codex, Cursor, OpenCode and dozens more, and the same command installs a skill for whichever of them you pick. That is why nearly every skill page on this site — and most skill READMEs — shows a npx skills add line rather than per-agent instructions.

Two names it gets confused with

• antfu/skills is not a CLI. It is a collection of skills that you install with this CLI.
• skills-cli on npm is a different, unrelated package. The command people mean is npx skills, with no suffix.

Skills are not the only extension format. Claude Code plugins install with /plugin commands instead, and our guide to agent plugins covers where the two differ.

npx skills add: Every Address It Accepts

add takes a source — where the skills live — and optionally which skills from it you want. install, i and a are aliases.

The flags that matter most:

• -g, --global — install for your user, not the current project.
• -a, --agent — which agents to install for; '*' means all of them.
• -s, --skill — which skills from the source; '*' means all.
• -y — skip the prompts. --all is shorthand for all skills, all agents, no prompts.
• --copy — copy files into each agent's folder instead of linking them.
• -l, --list — list what a source contains without installing.

What the @ Part Has to Match

The text after @ is compared — case-insensitively — with the name: field in each SKILL.md's frontmatter. Not the folder the SKILL.md sits in. Most of the time the two are the same, which is why this goes unnoticed until they are not.

Vercel's React skill is the standard example. It lives in a folder called react-best-practices, but its frontmatter says name: vercel-react-best-practices. So:

# fails: "No matching skills found for: react-best-practices"
npx skills add vercel-labs/agent-skills@react-best-practices

# works
npx skills add vercel-labs/agent-skills@vercel-react-best-practices

The same rule applies to --skill. If an install command copied from a README or an agent fails this way, open the SKILL.md and use what its name: line says. A SKILL.md with no name or no description is skipped entirely, with a warning.

Every @ install command on this site is built from the frontmatter name, which is why some of ours differ from the folder names you see on GitHub.

Where Skills Are Installed

A project install keeps one real copy of each skill in .agents/skills/<name>/, then links each agent you chose to that copy. For Claude Code the link is .claude/skills/<name>. Agents that already read .agents/skills directly, such as Cursor, need no link.

Linking is the default because it means one update reaches every agent. If a tool you use does not follow symlinks, install with --copy.

skills-lock.json records where each skill came from and a hash of what was installed, so update knows what to fetch. Commit it if you want a teammate's checkout to install the same set.

One surprise: npx skills list may show agents you never chose. Several agents read the same .agents/skills folder, so a skill installed for one is visible to all of them.

Every Command at a Glance

If you are writing your own skill, npx skills init gives you the frontmatter shape, and our step-by-step guide covers the rest. To have your agent search for skills on its own, install Find Skills: npx skills add vercel-labs/skills@find-skills.

npx skills update (and Why check Is Not a Dry Run)

npx skills update re-fetches each installed skill from the source recorded in the lock file. With no arguments it updates all of them; name skills to limit it. Add -g for global skills, and -y to skip the prompts.

check does the same thing. In the CLI's source, check, update and upgrade all call the same function. If you run check expecting a report of what is out of date, you get the updates instead.

That matters because an update is a new install. A skill is instructions your agent follows, and the new version can say something different from the one you read. For skills you rely on, look at what changed upstream before you update. Every skill page here shows the date of the last commit to the skill's own folder.

Two update problems recur in the project's issue tracker: updates that report they cannot find the lock file, and global updates failing on Windows. When an update fails on a skill, reinstalling it with add writes a fresh lock entry.

What It Does and Does Not Check for You

The CLI copies files. It does not run anything from the skill. The only programs it starts are git and gh, to fetch the source. A skill's scripts run later, if and when your agent decides to run them.

That still leaves the most important part to you:

• It does not show you the SKILL.md. --list shows each skill's name and description, not its instructions.
• Its risk badges depend on telemetry. For public GitHub repos, the CLI asks a Vercel service for a risk rating per skill — Critical, High, Med, Low or Safe — and shows it before installing. That request is skipped when telemetry is off, so opting out of telemetry also opts you out of the badges.
• Telemetry is on by default. It sends the CLI version, whether you are in CI, the detected agent, and skill and repo identifiers for public repos. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to turn it off.
• It installs whatever is at the address today. If a repo is deleted, renamed or taken over, the same command now fetches something else, or fails.

“Review skills before use; they run with full agent permissions.” — the last line npx skills add prints.

Two minutes of reading is enough: check that the repo is still there and is who you think it is, search the SKILL.md for anything piped into a shell, and ask what the skill is built to do. Issue 005 of The Manifest walks through those three checks. Our methodology lists what we will not list at all.

Common Errors and What They Mean

“No matching skills found for: …”

The name after @ or --skill is not any skill's frontmatter name. You almost certainly used the folder name. Run npx skills add owner/repo --list to see the real names.

“Authentication failed for https://github.com/…”

Either the repo is private, or it does not exist. For a public skill, a non-existent repo is far more likely — git reports a missing repo as an authentication failure. Check the address on GitHub. For a repo you do have access to, the CLI tries your git credentials, then gh, then SSH; the error message includes an SSH form to retry with.

“No skills found”

The source has no SKILL.md the CLI recognises — or its skills are missing name or description and were skipped. Look for warnings above the error — each skipped SKILL.md is named with the reason.

npm warns EBADENGINE

Your Node is older than 22.20. Upgrade Node; do not ignore it, because a failure later in the run will be harder to read.

The skill installed, but my agent does not see it

Check where it went. A project install is only visible in that project; -g makes it available everywhere. If your agent does not follow symlinks, reinstall with --copy. Then restart the agent session, since many agents read their skills when a session starts.

Frequently Asked Questions

How We Verified This

Checked on October 4, 2026 against skills 1.7.0 from npm, last published September 17, 2026. Command names, aliases, flags, the frontmatter-name match, the check alias, and the telemetry and risk-badge behaviour were read in the package's built source. Installs, the @ name failure, --list and remove were run in an empty scratch directory with telemetry disabled. Recurring problems come from the issue tracker on vercel-labs/skills.

The CLI changes often. If something here no longer matches what you see, tell us.