Frank
651924a4bc
Three parallel trees documented the same ecosystem: omp-docs/skills/
(two overview pages), tools/npx-skills/ (10 pi-era npm pages), and
tools/vercel-labs-skills/ (11 CLI pages), plus a fourth leaderboard page
at engineering/skills-ecosystem.md. Verbatim overlap (identical SKILL.md
field tables in skills-spec.md vs skill-format.md; 13-agent vs 68-agent
copies of the same upstream table). Consolidated to four concept pages:
- skills/agent-skills.md: standard, format, loading, authoring (merges
skills-spec, skill-format, skill-file-structure, skill-loading,
best-practices, skills-vs-extensions)
- skills/skills-cli.md: CLI reference (merges commands, source-formats,
installation-scope, skill-discovery, lock-file, env-variables,
agent-support, related-links)
- skills/store-wiring.md: moved, fleet ops, links retargeted
- skills/ecosystem.md: replaces skills-ecosystem.md; stale 2026-08-12
top-50 table dropped, replaced with a live top-10 re-queried from the
skills.sh API tonight and the API contract re-verified (zero-based,
200/page, {skills,total,hasMore,page}, total 9909)
All facts re-verified 2026-10-19 against primary sources:
agentskills.io, vercel-labs/skills README + src/cli.ts (command set,
--full-depth) + src/skill-lock.ts (v3 lock, XDG path, wipe-on-old),
live skills.sh API. Deleted superseded core/index-doc.md (old pi-era
docs index). Retargeted all inbound links (tools/index, engineering x3,
packages x3, pi/skills, core/index). Pi-era npm skill packaging is
listed as archived under /pi/.
Refs #29
128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
---
|
|
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)
|