---
type: reference
title: Skills CLI
description: "The Vercel Labs `skills` CLI: commands, sources, install scopes, discovery rules, lock file, environment variables, and the agent registry."
tags:
  - skills
  - cli
  - vercel
  - meta-installer
resource: https://github.com/vercel-labs/skills
timestamp: 2026-10-19
verified: 2026-10-19
---

# Skills CLI

`npx skills` is the CLI for the open agent-skills ecosystem
([vercel-labs/skills](https://github.com/vercel-labs/skills)). It is a
meta-installer: it pulls `SKILL.md` bundles from a source and links or copies
them into each supported agent's skill directory. No global install; run via
`npx`. Version 1.7.2 (`package.json`, 2026-10-19).

## Commands

| Command | Aliases | Purpose |
|---------|---------|---------|
| `skills add <source>` | `a` | Install skills from a source. |
| `skills use <source>[@skill]` | | Emit a prompt for one skill (pipe to an agent) or launch an agent with `--agent`, without installing. |
| `skills list` | `ls` | List installed skills (`-g` global only, `-a <agent>` filter). |
| `skills find [query]` | | Interactive (fzf-style) or keyword search; `--owner <org>` scans an org. |
| `skills update [skills...]` | | Update installed skills to latest; `-g`/`-p` scope, `-y` auto-scope. |
| `skills remove [skills]` | `rm`, `r` | Remove installed skills from agents. |
| `skills init [name]` | | Create a `SKILL.md` template. |
| `skills experimental_install` | `i`, `install` | Restore installs recorded in the lock file. |
| `skills experimental_sync` | | Sync installed skills against sources. |
| `skills check` | | Report drift: GitHub tree SHA vs locked `skillFolderHash`. |

`skills check` and `skills update` share a dispatch path in `src/cli.ts`
(2026-10-19). For `check`/`update`, only GitHub-backed skills carrying both
`skillFolderHash` and `skillPath` are compared.

### `add` options

| Option | Effect |
|--------|--------|
| `-g, --global` | User directory instead of project. |
| `-a, --agent <agents...>` | Target specific agents (`'*'` for all). |
| `-s, --skill <skills...>` | Specific skills by name (`'*'` for all). |
| `-l, --list` | List the source's skills without installing. |
| `--copy` | Copy instead of symlink. |
| `-y, --yes` | Skip prompts (CI-friendly). |
| `--all` | All skills to all agents, no prompts. |
| `--full-depth` | Discover `SKILL.md` outside standard container dirs too. |

## Sources

GitHub shorthand (`owner/repo`), full GitHub URL, a tree path to one skill
(`.../tree/main/skills/<name>`), GitLab URL, Azure DevOps URL, any git URL, a
local path, or a direct download URL (single `SKILL.md`, or `.zip`/`.tar`/
`.tar.gz`/`.tgz`). Private repos reuse the credentials git already has;
`GITHUB_TOKEN`/`GH_TOKEN` override for API access. Direct downloads cap at
10 MiB compressed, 25 MiB extracted, 1000 files (override with
`SKILLS_DOWNLOAD_MAX_BYTES`, `SKILLS_EXTRACT_MAX_BYTES`,
`SKILLS_EXTRACT_MAX_FILES`).

## Install scope and method

| Scope | Flag | Location |
|-------|------|----------|
| Project | default | `./<agent>/skills/` |
| Global | `-g` | `~/<agent>/skills/` |

Symlink (recommended: one canonical copy, easy update) or `--copy` (independent
copies, for hosts where symlinks are unsupported).

## Skill discovery in a source repo

The CLI walks each container directory up to three levels: flat
(`skills/<name>/SKILL.md`) and one- or two-level catalog layouts. Containers:
repo root, `skills/` (and `.curated`/`.experimental`/`.system`), plus
per-agent dirs (`.claude/skills/`, `.agents/skills/`, `.pi/skills/`, and
dozens more). A `SKILL.md` at a shallower level shadows deeper ones.
`--full-depth` also scans outside containers (`examples/`, `tests/`). If a
`.claude-plugin/marketplace.json` or `plugin.json` exists, its declared skill
paths load too (Claude Code marketplace compatibility). Nothing found in
containers triggers a recursive search.

## Lock file

| Type | Path |
|------|------|
| Global | `$XDG_STATE_HOME/skills/.skill-lock.json`, else `~/.agents/.skill-lock.json` |
| Project | `skills-lock.json` (commit it) |

Schema **v3**; key field `skillFolderHash` (GitHub tree SHA per skill folder).
A lock file older than v3 is wiped, not migrated — reinstall to repopulate
(`src/skill-lock.ts`, 2026-10-19).

## Environment variables

| Variable | Effect |
|----------|--------|
| `INSTALL_INTERNAL_SKILLS` | `1`/`true` reveals `metadata.internal: true` skills. |
| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry. |
| `DO_NOT_TRACK` | Alternative telemetry opt-out. |
| `GITHUB_TOKEN`, `GH_TOKEN` | Explicit GitHub API token. |

## Agent registry

79 agents supported (upstream README + `--agent` registry, checked 2026-10-19);
the CLI auto-detects installed agents, prompting when it finds none. Each agent
maps to a project and global path (e.g. `claude-code` → `.claude/skills/` /
`~/.claude/skills/`; `pi` → `.pi/skills/` / `~/.pi/agent/skills/`). The
authoritative table lives in the upstream README; this bundle does not mirror
it because the list churns. omp is not a registered agent — see
[Skill Store Wiring](/skills/store-wiring.md).

## Citations

- [vercel-labs/skills README](https://github.com/vercel-labs/skills) — 2026-10-19.
- `src/cli.ts`, `src/skill-lock.ts`, `package.json` at `vercel-labs/skills@main` — 2026-10-19.

## See Also

- [The Agent Skills Standard](/skills/agent-skills.md)
- [Skill Store Wiring](/skills/store-wiring.md)
- [Skills Ecosystem](/skills/ecosystem.md)