npx skills and skills.sh: a complete guide to the skills CLI

TL;DR

• npx skills runs the open-source skills CLI from Vercel Labs. npx skills add owner/repo installs Agent Skills from GitHub, any git host or a local path into 79 supported coding agents. skills.sh is the directory and leaderboard built on the CLI’s anonymous install telemetry.
• One install serves several agents. The CLI keeps a canonical copy in .agents/skills, which Codex and Cursor read directly, and symlinks it into .claude/skills for Claude Code.
• Project installs write skills-lock.json with a source and a SHA-256 hash of every file per skill. Commit it, pin git refs when exact content matters, and know that the restore command is still experimental.
• Every install ends with the same line: “Review skills before use; they run with full agent permissions.” Take it literally.

npx skills is the command that runs the open-source skills CLI, an MIT-licensed npm package from Vercel Labs that installs Agent Skills (folders containing a SKILL.md file) into coding agents such as Claude Code, Codex and Cursor. The core command is npx skills add owner/repo; around it sit commands to preview, list, search, update, remove, scaffold and restore skills. skills.sh is the web directory that ranks skills by the CLI’s anonymous install telemetry and gives each one a page with its install command. This guide covers every command in version 1.7.4, checked against the CLI’s --help output and its source at the v1.7.4 tag, and uses six open-source skills from the build-with-ai-hq organization as worked examples. Install results come from a test run on October 28, 2026.

What the skills CLI and skills.sh are

The skills package describes itself as “The open agent skills ecosystem”. Its README says it requires Node.js 22.20 or later and supports OpenCode, Claude Code, Codex, Cursor “and 75 more”. Running it through npx fetches and executes the package without a global install, which is why every command in this guide starts with npx skills.

A skill, in the Agent Skills specification, is a directory with a SKILL.md file whose YAML frontmatter carries a name and a description, followed by Markdown instructions and optional scripts/, references/ and assets/ folders. Agents read only the name and description at startup and load the rest when a task matches. The CLI’s job is getting those folders into the right directory for each agent and keeping them current.

skills.sh is the directory on top. Its documentation says the leaderboard “ranks skills based on anonymous telemetry data collected from the skills CLI”, that skills appear automatically once users install them, and that a badge can show install counts in a README. It also has an Official section for skills published by the companies behind a technology, a security audits page combining results from Gen Agent Trust Hub, Socket and Snyk, and “packs” that bundle skills into one install command. It is explicit about its limits: “we cannot guarantee the quality or security of every skill listed on skills.sh.” The CLI’s find command searches the same index from the terminal.

How one install serves Claude Code, Codex and Cursor

One project install serves several agents because many of them read the same directory. The CLI writes a canonical copy to .agents/skills/<name>, which Codex and Cursor read natively, and creates a symlink from .claude/skills/<name> to that copy for Claude Code, which reads only its own directory.

The CLI’s agent table records each agent’s paths:

The agents’ own documentation confirms the layout. Codex scans .agents/skills in every directory from the working directory up to the repository root and follows symlinked folders. Cursor’s skill directories include .agents/skills/ and .cursor/skills/, and for compatibility it also reads .claude/skills/ and .codex/skills/. Claude Code accepts a symlinked skill folder and loads the target once.

The October 28 test shows the result. After installing the six build-with-ai-hq skills with -a claude-code -a codex -a cursor, the CLI reported each as “universal: Codex, Cursor” and “symlinked: Claude Code”, and .claude/skills held only links (excerpt, two of six, dates trimmed):

lrwxr-xr-x  agent-skills-for-teams -> ../../.agents/skills/agent-skills-for-teams
lrwxr-xr-x  secure-llm-apps -> ../../.agents/skills/secure-llm-apps

Because several agents share .agents/skills, npx skills list showed each skill as available to “Antigravity, Claude Code, Codex, Cursor, Gemini CLI +1 more”, more agents than the three requested. Pass --copy for independent copies where symlinks are not wanted; per the installer source, Windows uses directory junctions and the CLI falls back to copying if a link cannot be created.

Project and global scope

Project scope is the default and writes into the current repository, where the skill can be committed and shared. Global scope, -g, writes into each agent’s user directory so the skill is available in every project on the machine. Teams usually want project scope for shared skills and global scope for personal ones.

The two lock files differ. The project lock hashes the files on disk; the global lock records GitHub tree SHAs and moves to $XDG_STATE_HOME/skills/ when that variable is set. update, list and remove take -g to act on global installs, and update -p limits itself to project skills.

The add command and its flags

npx skills add <source> resolves a source, discovers every SKILL.md in it, asks which skills and agents to install unless told, copies the files and writes the lock entry. Sources can be GitHub shorthand, a full URL, a tree URL pointing at one skill, GitLab, Azure Repos, any git URL, a local path or a direct download.

npx skills add build-with-ai-hq/llm-cost-reduction                 # GitHub shorthand
npx skills add https://github.com/build-with-ai-hq/llm-cost-reduction
npx skills add build-with-ai-hq/llm-cost-reduction#main            # pin a branch or tag
npx skills add git@github.com:build-with-ai-hq/llm-cost-reduction.git
npx skills add ./my-local-skills

Private repositories use the credentials already configured: per the CLI reference, git credentials first, then an authenticated GitHub CLI, then SSH. The flags from --help:

Direct download URLs may point at a SKILL.md or an archive; the reference caps downloads at 10 MiB, extracted content at 25 MiB and archives at 1,000 files unless overridden. The aliases a, i and install all run add.

Every other command

Beyond add, version 1.7.4’s help lists eight more commands for using, listing, searching, removing, updating, scaffolding, restoring and syncing skills. Two of them carry an experimental_ prefix, which the reference says means “names, options, and behavior may change”.

Three details matter in practice. use pipes cleanly into an agent, as in npx skills use owner/repo@skill | claude, which is a low-commitment way to try a skill. update hashes each skill in the fresh clone the same way add did and skips unchanged ones. And the README advertises npx skills check for “available updates”, but in 1.7.4 the dispatcher routes check to the same handler as update, so it installs updates rather than only reporting them. A later commit on the main branch changes that; until a release ships it, treat check as update.

Two smaller behaviors are worth knowing. find queries the skills.sh search index (the source lets SKILLS_API_URL point it elsewhere) and prints each result’s skills.sh page, and --owner restricts results to one GitHub organization or user. remove owner/repo removes every skill installed from that exact lock source in one step, which is the clean way to drop a whole collection.

skills-lock.json and reproducible team installs

A project install writes skills-lock.json at the repository root. Each entry records where the skill came from, the path of its SKILL.md in that source, an optional git ref and a SHA-256 hash of the installed files. Committing it lets a teammate or CI job restore the same set of skills.

From the October 28 test:

"secure-llm-apps": {
  "source": "build-with-ai-hq/secure-llm-apps",
  "sourceType": "github",
  "skillPath": "SKILL.md",
  "computedHash": "5fdb07a27bb937b012f2e5a7bfe366a667b8591c9d2102c3b064daa9a76e3013"
}

The hash function collects every file in the skill folder, sorts them by relative path, and feeds each path and its contents into SHA-256, so any edit, addition or rename changes the hash. The file is deliberately timestamp-free and sorted alphabetically, so two branches adding different skills merge without conflict.

Four facts shape how far the lock can be trusted in 1.7.4:

• Refs are optional. The six test entries have no ref, so a restore fetches the default branch as it is that day. Install with owner/repo#tag and the ref is recorded.
• The hash drives updates, not restores. update compares it to decide what changed. experimental_install reinstalls from the recorded source and does not refuse a mismatch; a --frozen-lockfile option landed on main after 1.7.4.
• Restore writes only .agents/skills. Per the source, it does not create agent-specific links, so Claude Code users should commit the .claude/skills symlinks or re-run add with -a claude-code.
• Packaged skills sync separately. Entries from npm packages are linked by experimental_sync, not restored by experimental_install, so install npm dependencies first.

experimental_sync (alias sync) is the npm-native path. It reads the installed dependencies listed in package.json, discovers a root SKILL.md, skills/<name>/SKILL.md or dist/skills/<name>/SKILL.md in each package, and links them into .agents/skills/ so they update with the dependency. A project can also declare skills directly:

{
  "skills": ["npm:agent-browser", "build-with-ai-hq/llm-cost-reduction#main"],
  "scripts": { "prepare": "skills experimental_sync -y" }
}

An npm: entry points at an installed package; any other entry is a git source fetched into the project, and the reference advises pinning a git ref “when you need reproducible remote content”. --dry-run shows the plan without changing anything.

For teams that need stronger guarantees, the safest pattern in 1.7.4 is to commit .agents/skills/ itself alongside the lock file, so the reviewed bytes are the ones that ship.

Security: review before install

Skills are instructions an agent follows and scripts it may run, with whatever permissions the agent already has. The CLI says so after every install, in add.ts: “Review skills before use; they run with full agent permissions.” Review means reading every file, not only SKILL.md.

The CLI adds two signals. For repositories GitHub confirms are public, add requests partner audit data and prints a table with Gen, Socket and Snyk columns, linking to the skill’s skills.sh page; the same results appear on the audits page. And telemetry, which sends skill identifiers for confirmed-public GitHub repositories, can be disabled with DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1, which also turns off the audit requests.

Neither replaces review. A third-party skill is also a channel for prompt injection: its text enters the agent’s context as instructions, and the agent-skills-for-teams review checklist warns that “prompt injection through skills is real for third-party skills”. A practical checklist, drawn from that skill:

• Scripts contain no curl ... | sh, sudo, broad rm -rf, eval of input or reads of ~/.ssh or ~/.aws.
• Every network call a script makes is documented in SKILL.md.
• Instructions never tell the agent to disable permission prompts or override the user.
• The source is pinned to a ref and re-reviewed on every update.

That skill ships lint_skills.py, which checks spec rules and flags risky script patterns. Run against all six installed skills in the test, it reported “0 error(s), 0 warning(s)”. The agent-side controls are covered in Claude Code security and the sibling AI agent security guide.

A team workflow for shared skills

A team gets reproducible, reviewable skills by treating them like dependencies: pin the source, commit what was installed, review changes in pull requests and lint in CI. The CLI supplies the mechanics; the discipline around it is the team’s.

1. Pin the source. npx skills add owner/repo#<ref> records the ref in the lock. A branch or tag works, and per the git helper a full 40-character commit SHA also works through a fetch-by-SHA fallback; abbreviated SHAs do not.
2. Install at project scope, explicitly. Name the agents with -a and pass -y, so the result does not depend on which agents happen to be detected on one laptop.
3. Commit the installed files. .agents/skills/, the .claude/skills/ links and skills-lock.json go into one pull request, and the reviewer reads exactly what agents will load.
4. Lint in CI. agent-skills-for-teams includes a GitHub Actions workflow that runs lint_skills.py on every pull request touching skill directories and fails when a skill changes without a metadata.version bump. npx skills list --json gives a machine-readable inventory for the same job.
5. Update on a branch. npx skills update -p -y reinstalls only skills whose hash changed, so the diff names exactly which skills moved; review it like any dependency bump.
6. Remove cleanly. npx skills remove <name> deletes the skill from the agent directories and drops its entry from the project lock.

Worked example: six skills for LLM teams

The build-with-ai-hq organization publishes six MIT-licensed skills for teams building LLM apps and agents. Each installs with one npx skills add command and appears on skills.sh. All six installed for Claude Code, Codex and Cursor in the October 28 test, with zero lint errors.

# Preview, then install one skill for three agents without prompts
npx skills add build-with-ai-hq/secure-llm-apps --list
npx skills add build-with-ai-hq/secure-llm-apps -a claude-code -a codex -a cursor -y

# The other five
npx skills add build-with-ai-hq/llm-observability-stack -a claude-code -a codex -a cursor -y
npx skills add build-with-ai-hq/llm-cost-reduction -a claude-code -a codex -a cursor -y
npx skills add build-with-ai-hq/mcp-gateway-best-practices -a claude-code -a codex -a cursor -y
npx skills add build-with-ai-hq/ai-coding-agent-governance -a claude-code -a codex -a cursor -y
npx skills add build-with-ai-hq/agent-skills-for-teams -a claude-code -a codex -a cursor -y

# Personal install for Claude Code only, then keep current
npx skills add build-with-ai-hq/agent-skills-for-teams -g -a claude-code -y
npx skills list
npx skills update

Each skill uses Bifrost, Maxim AI’s open-source AI gateway, as its default control point for central enforcement such as per-developer keys, budgets and MCP tool allowlists; most of their audit steps and code fixes apply without it. agent-skills-for-teams also covers Bifrost’s Skills Repository, which serves versioned skills to Claude Code and Codex as a plugin marketplace, for teams that outgrow npx skills update. The six are ranked against each other in the best Claude Code skills.

Using installed skills

No extra step is needed after install. The agent sees each skill’s description and loads it when a request matches; in Claude Code, /secure-llm-apps invokes one directly, and Codex accepts $secure-llm-apps. Prompts built from the skills’ own trigger phrases:

• “Is my AI app secure? Do a security review of our RAG chatbot.” (secure-llm-apps)
• “Latency spiked and we have no visibility into our LLM calls.” (llm-observability-stack)
• “Our OpenAI bill spiked. Which feature is burning tokens?” (llm-cost-reduction)
• “Our skill never triggers. Fix the SKILL.md description.” (agent-skills-for-teams)

Claude Code budgets the skill listing at 1% of the context window and truncates each description at 1,536 characters, per its skills documentation, so installing only the skills a repository needs keeps triggering precise. Agent-specific details are in the sibling guides to Codex skills, Cursor skills and Claude Code for teams, and gateway routing for all three in AI gateways for Claude Code, Codex and Cursor.

Limits of this guide

This guide describes version 1.7.4, checked against the source at that tag on October 28, 2026; the main branch has moved since, and two commands are explicitly experimental. The test covered installation and linting in an empty repository on macOS, not skill outcomes in a real codebase, Windows, or private-repository authentication. Install counts on skills.sh were not used as evidence of quality.

The skills CLI does one thing well: it turns a git repository of SKILL.md folders into working skills for many agents from a single canonical copy, and records what it installed. The parts teams need to add are review, ref pinning and a decision about whether to commit the installed files. Start with a preview, npx skills add build-with-ai-hq/secure-llm-apps --list, read what it would install, and only then run it.