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
5.4 KiB
type, title, description, tags, resource, timestamp, verified
| type | title | description | tags | resource | timestamp | verified | ||||
|---|---|---|---|---|---|---|---|---|---|---|
| reference | Skills CLI | The Vercel Labs `skills` CLI: commands, sources, install scopes, discovery rules, lock file, environment variables, and the agent registry. |
|
https://github.com/vercel-labs/skills | 2026-10-19 | 2026-10-19 |
Skills CLI
npx skills is the CLI for the open agent-skills ecosystem
(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.
Citations
- vercel-labs/skills README — 2026-10-19.
src/cli.ts,src/skill-lock.ts,package.jsonatvercel-labs/skills@main— 2026-10-19.