Vercel Labs shipped a CLI that treats agent capabilities like npm packages. The Skills CLI resolves GitHub shorthand (owner/repo), pins versions, and generates prompts that work across Claude Code, Cursor, Codex, and 75+ other agents. It solves the distribution problem for agent tooling the same way npm solved it for JavaScript libraries.
The plumbing matters because agent tools are no longer bespoke scripts tied to a single runtime. They are portable artifacts with namespaces, version constraints, and a registry at skills.sh. This is the first package manager for agent capabilities.
The Distribution Problem
Agent frameworks ship with tool registries, but those registries are framework-specific. LangChain tools do not run in Cursor. MCP servers require a host that speaks the Model Context Protocol. Custom tools live in project directories or get copy-pasted between codebases.
Skills CLI decouples tool definitions from agent runtimes. A skill is a directory of Markdown files, JSON schemas, or executable scripts. The CLI fetches skills from remote sources, writes them to disk, and generates prompts that agents consume. The agent does not need to know about the Skills CLI. It only sees the generated prompt.
This separation creates a distribution layer. Skills become versioned, shareable, and discoverable outside of any single agent’s plugin ecosystem.
How Source Resolution Works
The CLI accepts six source formats:
| Format | Example | Behavior |
|---|---|---|
| GitHub shorthand | vercel-labs/agent-skills | Clones default branch from GitHub |
| Full GitHub URL | https://github.com/vercel-labs/agent-skills | Clones from URL |
| Direct skill path | https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines | Fetches single skill subdirectory |
| GitLab URL | https://gitlab.com/org/repo | Clones from GitLab |
| Azure Repos URL | https://dev.azure.com/org/project/_git/repo | Clones from Azure DevOps |
| Local path | ./my-skills | Copies from filesystem |
Version pinning uses Git refs. vercel-labs/agent-skills@v1.2.0 checks out the tag. vercel-labs/agent-skills@main tracks the branch. Without a ref, the CLI uses the default branch.
The resolver does not require authentication for public repos. Private repos use SSH keys or Git credential helpers already configured on the machine. The CLI does not manage credentials itself.
Persistent vs Ephemeral Installation
Two commands expose different usage patterns:
skills add installs skills persistently. It clones the repo into ~/.skills/ and updates a local index. Installed skills are available to all agents on the machine. This is the equivalent of npm install -g.
skills use generates a one-time prompt. It writes skill files to a temp directory, prints the prompt to stdout, and exits. The temp directory is cleaned up after the session. This is the equivalent of npx without installation.
The --agent flag changes behavior. Without it, skills use prints the prompt and stops. With it, the CLI starts an interactive agent session and passes the prompt as input. The agent sees the skill files in the temp directory.
# Generate prompt, pipe to Claude
npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
# Start Cursor with the skill loaded
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent cursorThe separation between prompt generation and agent invocation keeps the CLI agent-agnostic. It does not need to know how Cursor or Claude Code parse prompts. It only needs to know how to format skill files into a prompt string.
Cross-Agent Compatibility
The CLI supports 75+ agents because it does not integrate with agent APIs. It generates text prompts. The agent reads the prompt and decides what to do with it.
Skills are Markdown files with optional JSON schemas. A skill directory looks like this:
web-design-guidelines/
skill.md # Human-readable instructions
schema.json # Optional structured input/output spec
examples/ # Optional usage examplesThe CLI concatenates these files into a single prompt. The agent parses the Markdown and extracts instructions. If the agent supports structured inputs, it reads schema.json. If not, it ignores the file.
This works because modern agents are trained to follow Markdown instructions. The skill format is not a protocol. It is a convention. The CLI does not enforce schema validation or tool registration. It trusts the agent to interpret the prompt.
The trade-off is flexibility vs. guarantees. Skills cannot assume the agent supports function calling, streaming, or structured outputs. They must work as plain text instructions. This limits what skills can express but maximizes compatibility.
The Registry and Badge System
The skills.sh registry provides discovery and metadata. Each skill gets a badge:
[](https://skills.sh/vercel-labs/agent-skills)The badge links to a registry page with install instructions, version history, and usage stats. The registry does not host skill files. It indexes GitHub repos and provides a search interface.
The registry solves the discovery problem. Without it, skills are scattered across GitHub repos with no central index. With it, developers can browse skills by category, popularity, or compatibility.
The registry does not enforce quality or security. It is a directory, not a gatekeeper. Anyone can publish a skill by pushing a repo to GitHub and adding a badge. The CLI does not verify signatures or run sandboxed execution. It trusts the user to vet skills before installing them.
Orchestration Flow
A typical workflow:
- Developer runs
npx skills add vercel-labs/agent-skills - CLI clones the repo to
~/.skills/vercel-labs/agent-skills - CLI indexes skill directories and updates
~/.skills/index.json - Developer runs
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent cursor - CLI reads skill files from
~/.skills/vercel-labs/agent-skills/skills/web-design-guidelines - CLI writes files to
/tmp/skills-session-abc123/ - CLI generates a prompt string with file paths and instructions
- CLI invokes
cursorwith the prompt as input - Cursor reads the prompt, parses instructions, and starts an interactive session
- Session ends, CLI cleans up
/tmp/skills-session-abc123/
The CLI does not manage agent state. It does not track which skills are loaded in which sessions. It does not persist session history. It is a stateless tool that generates prompts and exits.
Security Boundaries
The CLI runs with the user’s permissions. It clones repos, writes to disk, and invokes executables. It does not sandbox skill execution. If a skill contains malicious code, the CLI will run it.
Three attack vectors:
Malicious skills: A skill repo can include executable scripts that run during installation or use. The CLI does not scan for malware or validate code. Users must vet skills before installing them.
Dependency confusion: The CLI resolves GitHub shorthand without namespace verification. skills add malicious/agent-skills will clone from the malicious org, not the vercel-labs org. Users must specify the full namespace.
Prompt injection: Skills are Markdown files that become agent prompts. A malicious skill can include instructions that override the agent’s system prompt or exfiltrate data. The CLI does not sanitize skill content.
The CLI does not provide isolation. It is a distribution tool, not a sandbox. Security depends on the user’s ability to audit skills before installation.
Failure Modes
Network failures: The CLI requires network access to clone repos. If GitHub is unreachable, installation fails. The CLI does not cache repos or provide offline mode.
Version conflicts: The CLI does not resolve version constraints across skills. If two skills depend on incompatible versions of a third skill, the CLI installs both. The agent sees duplicate files and may behave unpredictably.
Agent incompatibility: The CLI generates prompts but does not verify agent compatibility. If an agent does not support Markdown instructions, the skill will not work. The CLI does not provide fallback behavior.
Disk space exhaustion: The CLI clones entire repos, not individual skills. A large repo with many skills consumes disk space even if only one skill is used. The CLI does not prune unused files.
Deployment Shape
The CLI is a Node.js package distributed via npm. It runs on any machine with Node.js 18+. It does not require a server or cloud service. The registry at skills.sh is a static site hosted on Vercel.
The CLI does not phone home. It does not send telemetry or usage data. It does not require authentication or API keys. It is a local-first tool.
The registry provides optional metadata but is not required for CLI operation. Developers can use the CLI without ever visiting skills.sh. The registry is a discovery layer, not a dependency.
Technical Verdict
Use Skills CLI when:
- You need to share agent capabilities across multiple agents (Claude, Cursor, Codex)
- You want version control and namespacing for agent tools
- You prefer Markdown-based tool definitions over code-based integrations
- You need a distribution mechanism that works without framework lock-in
Avoid Skills CLI when:
- You need sandboxed execution or security guarantees
- You require structured tool calling with type validation
- You need dependency resolution across conflicting skill versions
- You want offline-first operation without network access
The CLI is a distribution layer, not an execution runtime. It solves the packaging problem but delegates security, validation, and execution to the agent. It is npm for agent tools, with the same trade-offs: convenience and portability at the cost of isolation and guarantees.