Vercel Skills CLI

What It Does

The Vercel Skills CLI (skills, published as the npm package skills at v1.5.18) is the package manager and runtime for the open agent skills ecosystem. It does for agent SKILL.md files what npm does for JavaScript packages: it resolves sources (GitHub shorthand, full URLs, GitLab, git URLs, local paths), fetches skill files via a fast blob-based download API or git clone, runs security risk assessment against three scanners (Gen, Socket, Snyk), and installs to any of 73 supported coding agents at their correct platform-specific paths. The tool targets developers and teams who want to share, version, and reproduce agent skill configurations across projects and machines. It is built and maintained by Vercel Labs (the official Vercel organization that also hosts the AI SDK), with 26,285 GitHub stars, 8.19 million weekly npm downloads, and 85 published releases.

The Good

The agent coverage is the broadest of any tool GearScope has reviewed. The CLI supports 73 distinct coding agents, each with a correctly mapped project path and global path. This includes first-class support for Hermes Agent (.hermes/skills/, with HERMES_HOME env override), OpenClaw (skills/ project, ~/.openclaw/skills/ global, with fallback detection for .clawdbot and .moltbot), Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, and 64 more. Each agent has a dedicated config block in src/agents.ts with its own detectInstalled function, so the CLI knows which agents are actually present on your machine rather than blindly writing to every directory.

The security model is real, layered, and tested. Three independent scanners run before every install: Gen, Socket, and Snyk. The output is rendered inline in the install confirmation panel with a direct link to the full risk report on skills.sh. Beyond third-party scanning, the CLI implements its own defenses: src/sanitize.ts strips all terminal escape sequences (CSI, OSC, DCS, PM, APC, C1 codes) from untrusted skill metadata before display, explicitly defending against CWE-150 (terminal escape injection) where a malicious SKILL.md frontmatter could clear the screen or forge CLI output. Path traversal is blocked at two layers: sanitizeName in installer.ts enforces kebab-case and rejects traversal, and sanitizeSubpath / isSubpathSafe in source-parser.ts reject .. segments and backslash traversal. The archive unpacking path (src/providers/wellknown.ts) rejects symlinks (tar typeFlag 0x31/0x32, ZIP mode 0o120000/0o10000), encrypted entries, and enforces a 50MB unpacked / 1000-file limit as zip bomb defense. Each of these defenses has dedicated test coverage.

The test suite is large, fast, and mostly green. Running vitest produces 596 passed and 1 failed across 45 test files in 11 seconds. The source is 21,283 lines of TypeScript across src/ and tests/, with a test-to-source ratio of roughly 1:2. The coverage spans every command (add, use, list, remove, find, update, init), every source format (GitHub shorthand, URL, local path, git URL), cross-platform path normalization, XDG config handling, plugin manifest discovery, skill discovery at multiple depths, lock file hashing, and the security sanitization layer. The single failure (tests/dist.test.ts) is an environment issue: the test hardcodes pnpm build in an execSync call, and pnpm is not available on this host.

The lock file system makes skill installs reproducible. After installing a skill, the CLI writes a skills-lock.json containing the source, source type, skill path within the repo, and a SHA-256 computed hash of the installed files. Running experimental_install reads this lock file and restores the exact skill state. This is the agent-skills equivalent of package-lock.json, and it means a team can commit their skill dependencies and get identical installs across machines.

The skills use command is a useful innovation. Instead of installing a skill permanently, skills use owner/repo@skill-name fetches the skill, writes it to a temporary directory, and prints only the generated prompt to stdout. Piped into an agent (npx skills use owner/repo@skill | claude), this lets you try a skill ephemerally without modifying your skill directories. The command also supports --agent to launch a supported agent interactively with the prompt pre-loaded.

The Bad

The repository has no LICENSE file. The package.json declares "license": "MIT" and the npm package metadata confirms MIT, but there is no LICENSE or LICENSE.md file in the repository root. GitHub's API returns license: null for this reason, and the repo page shows no license badge. For a tool that 26,000-star projects and 8 million weekly downloads depend on, the absence of a LICENSE file is a real gap: it creates legal ambiguity about whether the MIT declaration in package.json constitutes a complete grant, and it prevents automated license-compliance tooling from confirming the terms. Adding a standard MIT LICENSE file is a one-file fix.

The --all flag documentation does not match the implementation. The README documents --all as "Shorthand for --skill '*' --agent '*' -y" for the remove command. In practice, remove --all selects all installed skills but does not skip the confirmation prompt. The interactive "Are you sure you want to uninstall?" dialog appears and blocks until input is provided, even though the docs imply -y is included. Additionally, passing --agent '*' directly is rejected by the validator: the CLI prints "Invalid agents: *" and lists all 73 valid agent names. The README explicitly documents npx skills remove my-skill --agent '*' as a valid command, but the code on line 87-93 of src/remove.ts filters * against the valid agent list and rejects it. The --all path works around this by skipping agent selection entirely (targeting all known agents), but the documented wildcard syntax for manual use is broken.

The dist test is fragile and environment-coupled. tests/dist.test.ts calls execSync('pnpm build', ...) directly, hardcoding the package manager. On any machine without pnpm installed globally (or where corepack is not enabled), this test fails. The project uses pnpm as its primary package manager and the CI workflows enable corepack, so this passes in CI. But it fails for anyone running the test suite with npm, yarn, or bun. A more resilient approach would detect the available package manager or run the build script via the Node API.

Telemetry is on by default with no first-run notice. The CLI collects anonymous usage telemetry (events for installs, searches, agent detection) and sends it to a backend. It can be disabled via DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1, and the code respects both. But there is no first-run prompt, no telemetry notice in the banner output, and no mention of telemetry in the interactive install flow. The README does document the environment variables in a table at the bottom, but a user who only runs npx skills add ... will not see them. For a tool that runs with full agent permissions and handles potentially sensitive project paths, opt-out telemetry without a visible notice is a reasonable concern.

Smoke Test Results

Tested on macOS (host) with Node v24.13.1. Dependencies installed via npm install. The CLI was run in dev mode (node src/cli.ts) and via npx skills@1.5.18. No special configuration required.

Run A - Fresh sandbox, no deps preinstalled

$ npx skills@1.5.18 --version
npm warn exec The following package was not found and will be installed: skills@1.5.18
1.5.18
✅ CLI runs via npx with zero local install

$ node src/cli.ts
[ASCII banner rendered]
$ npx skills add <package> Add a new skill
$ npx skills use <package>@<skill> Use a skill without installing
...
✅ Banner and command list display

$ node src/cli.ts init test-skill
Initialized skill: test-skill
Created: test-skill/SKILL.md
✅ init generates valid SKILL.md template

Pass rate: 3 of 3. The CLI works with zero configuration via npx and in dev mode.

Run B - Sandbox with deps preinstalled

$ npm install --silent
✅ Dependencies resolve cleanly

$ npx vitest run
Test Files 1 failed | 44 passed (45)
Tests 1 failed | 596 passed (597)
Duration 10.93s
✅ 596 of 597 tests pass (1 env-specific failure)

$ node src/cli.ts add vercel-labs/agent-skills --skill vercel-react-best-practices -a hermes-agent -a claude-code --copy -y
Security Risk Assessments: Gen=Safe, Socket=0 alerts, Snyk=Low Risk
Installed 1 skill (copied):
 ./.hermes/skills/vercel-react-best-practices (74 files)
 ./.claude/skills/vercel-react-best-practices (74 files)
✅ Skill fetched, security-scanned, installed to correct paths

$ node src/cli.ts list
vercel-react-best-practices ./.claude/skills/... Agents: Claude Code, Hermes Agent
✅ list shows installed skill and target agents

$ node src/cli.ts rm vercel-react-best-practices -y
Successfully removed 1 skill(s)
✅ remove deletes skill from all agent directories

Pass rate: 5 of 5. Install, test, list, and remove all produce correct results. The 1 test failure is the pnpm-hardcoded dist test.

Run C - Functional verification (does it do what it claims?)

$ node src/cli.ts add vercel-labs/agent-skills --list
Source: https://github.com/vercel-labs/agent-skills.git
Found 9 skills
✅ Remote discovery works (GitHub Trees API + blob fetch)

$ node src/cli.ts use vercel-labs/agent-skills@vercel-react-best-practices
[Full SKILL.md prompt printed to stdout with frontmatter + body]
✅ use generates ephemeral prompt without installing

$ cat skills-lock.json
{"version":1,"skills":{"vercel-react-best-practices":{
 "source":"vercel-labs/agent-skills","sourceType":"github",
 "skillPath":"skills/react-best-practices/SKILL.md",
 "computedHash":"ca7b0c0c6e5f2750..."}}}
✅ Lock file records source, type, path, SHA-256 hash

$ node src/cli.ts experimental_install
Restored vercel-react-best-practices (copied) from skills-lock.json
✅ Lock-file restore reproduces exact skill state

$ node src/cli.ts find typescript -y
wshobson/agents@typescript-advanced-types 53.6K installs
github/awesome-copilot@javascript-typescript-jest 11.7K installs
+ 3 more results
✅ find queries skills.sh search API with install counts

$ node src/cli.ts remove --agent '*'
Invalid agents: *
Valid agents: aider-desk, amp, antigravity, ... hermes-agent, ... (73 agents)
❌ Wildcard agent syntax documented in README is rejected by validator

Functional pass rate: 6 of 7. The wildcard agent failure is a documentation mismatch, not a missing feature (the --all flag achieves the same result through a different code path).

What the runs tell you

The CLI does exactly what it claims. Every core command (add, use, list, remove, find, init, update, lock-file restore) works correctly end to end, with security scanning baked into the install flow and correct file placement across agent directories. The test suite is 99.8% green, with the single failure being an environment-specific pnpm dependency in the dist test. The only functional gap is a documentation mismatch where the --agent '*' wildcard syntax is documented but rejected by the validator, though the --all flag provides the same capability.

Setup Walkthrough

1. Run any command directly with npx, no install needed: npx skills add vercel-labs/agent-skills. The CLI downloads on first run (approximately 2 seconds) and works immediately.

1. To install globally: npm install -g skills. This gives you the skills and add-skill binaries on your PATH.

1. Install a skill to specific agents: npx skills add owner/repo --skill skill-name -a hermes-agent -a claude-code -y. The -a flag targets specific agents, --skill selects by name, and -y skips prompts for non-interactive use.

1. List what is installed: npx skills list. Shows project and global skills with their target agents.

1. Search the registry: npx skills find react performance. Returns ranked results from skills.sh with install counts and direct install links.

1. Reproduce installs on another machine: commit the generated skills-lock.json, then run npx skills experimental_install to restore the exact skill set.

Post-install gotcha: if you want to disable telemetry, set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 in your environment before running any command. There is no first-run prompt for this.

Alternatives

1. Manual skill file management - Copy SKILL.md files directly to your agent's skills directory (for example .hermes/skills/). Zero dependencies, full control, but no version tracking, no security scanning, no lock files, and no search. Suitable for small, static skill sets that never change.

1. Claude Code plugin marketplace - The native Claude Code plugin system (.claude-plugin/marketplace.json). The skills CLI supports this format natively for discovery, so the two are complementary rather than competing. Use the marketplace if you are exclusively on Claude Code and want the native UX.

1. git submodules for skill repos - Track skill repositories as git submodules in your project. Gives you version pinning and reproducibility, but requires manual path configuration for each agent and provides no security scanning or search. More work, less safety.