dank/command-center
1
0 Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(skills): collapse three overlapping skills trees into one verified tree

Browse Source 
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
This commit is contained in:
Frank committed 2026-10-19 02:58:52 -07:00
1 parent e86e60af39
commit 651924a4bc
41 files changed
+439 -1686
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

omp-docs/skills/agent-skills.md
+105
View File
@@ -0,0 +1,105 @@
---
type: concept
title: The Agent Skills Standard
description: "The open Agent Skills standard: SKILL.md format, frontmatter fields, directory structure, progressive-disclosure loading, authoring practice, and how skills differ from extensions."
tags:
- skills
- agent-skills
- specification
- authoring
timestamp: 2026-10-19
verified: 2026-10-19
---
# The Agent Skills Standard
A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter
(`name` + `description`) followed by markdown instructions, plus optional
`scripts/`, `references/`, and `assets/`. The standard is maintained at
[agentskills.io](https://agentskills.io) and adopted by 79 coding agents
(upstream agent registry, checked 2026-10-19), so one skill works across
harnesses. The `skills` CLI installs them; see
[Skills CLI](/skills/skills-cli.md).
## SKILL.md format
```markdown
---
name: my-skill
description: What the skill does and when to use it.
---
# My Skill
Instructions the agent follows when the skill activates.
```
### Frontmatter fields
| Field | Required | Notes |
|-------|----------|-------|
| `name` | yes | Max 64 chars; lowercase `a-z`, `0-9`, hyphens; no leading/trailing or consecutive hyphens (`pdf-processing` good, `PDF-Processing`, `-pdf`, `pdf--processing` bad). Pi does not require the name to match the parent directory; the standard does. |
| `description` | yes | Max 1024 chars. The only text the agent sees when deciding whether to activate the skill. First sentence: what it does. Second: when to use it. |
| `license` | no | License name or reference to a bundled file. |
| `compatibility` | no | Max 500 chars; environment requirements. |
| `metadata` | no | Arbitrary key/value mapping. `metadata.internal: true` hides the skill from discovery unless `INSTALL_INTERNAL_SKILLS=1` (skills CLI convention). |
| `allowed-tools` | no | Space-delimited pre-approved tools (experimental; agent support varies — Zencoder and Kiro do not implement it). |
| `disable-model-invocation` | no | When `true`, the skill is hidden from the system prompt; users invoke it explicitly (`/skill:name`). |
### Directory structure
```
my-skill/
├── SKILL.md # Required entry point
├── scripts/ # Helper scripts (bash, js, python, ...)
├── references/ # Detailed docs, loaded on demand
├── assets/ # Templates, configs, binary data
└── config.json # Optional skill settings
```
Everything except `SKILL.md` is freeform. Scripts save tokens and improve
reliability when the same code would otherwise be regenerated per run.
## Loading: progressive disclosure
Harnesses (pi, omp, Claude Code, ...) load skills the same way:
1. At startup, scan configured skill locations; extract `name` + `description` only.
2. Inject the metadata list into the system prompt.
3. On a matching task, the agent reads the full `SKILL.md` and follows it,
referencing bundled scripts by relative path.
Only descriptions live in context permanently; full instructions load on demand.
On omp the load order is priority-ranked: authored `agent/skills/` (100) beats
the `~/.agents` store provider, which beats auto-learned
`agent/managed-skills/` (5). See [Skill Store Wiring](/skills/store-wiring.md).
## Skills vs extensions
| | Skills | Extensions |
|---|--------|------------|
| Format | Markdown (`SKILL.md`) + scripts | TypeScript (`.ts`) |
| Purpose | Instructions for the model | Code intercepting events, registering tools |
| Execution | The agent reads and follows | Runs in the harness runtime |
| Loading | On demand | Always loaded at startup |
| Trust model | Review the text (it instructs the model) | Review the code (it executes) |
A harness package may bundle both (pi did; omp extensions live in
`agent/extensions/`).
## Authoring practice
- Descriptions beat clever bodies: activation depends entirely on the description matching the user's words. "Extracts text and tables from PDF files, fills forms, merges documents" beats "Helps with PDFs."
- Keep `SKILL.md` focused; push long detail into `references/` (files load whole; split past roughly 500 lines).
- Skills instruct the model to run arbitrary commands, and scripts run with full user permissions. Review content before installing from untrusted sources.
- Document dependencies (tools, API keys, setup steps) inside the skill.
## Citations
- [Agent Skills specification](https://agentskills.io) — re-fetched 2026-10-19.
- [vercel-labs/skills README](https://github.com/vercel-labs/skills) — compatibility matrix, re-fetched 2026-10-19.
## See Also
- [Skills CLI](/skills/skills-cli.md) — install/use/update tooling.
- [Skill Store Wiring](/skills/store-wiring.md) — how the fleet provisions skills.
- [Skills Ecosystem](/skills/ecosystem.md) — registries and leaderboards.
omp-docs/skills/ecosystem.md
+77
View File
@@ -0,0 +1,77 @@
---
type: reference
title: Skills Ecosystem
description: "Registries and the leaderboard API for the open agent-skills ecosystem, with a live-verified install snapshot."
tags:
- skills
- skills-sh
- ecosystem
- registry
timestamp: 2026-10-19
verified: 2026-10-19
---
# Skills Ecosystem
The open agent-skills ecosystem is a set of registries over the shared
[Agent Skills standard](/skills/agent-skills.md), installed with the
[Skills CLI](/skills/skills-cli.md).
## Registries
| Registry | Focus |
|----------|-------|
| [skills.sh](https://skills.sh) | Primary registry and all-time install leaderboard. |
| [agentskill.sh](https://agentskill.sh) | Broad directory/marketplace. |
| [officialskills.sh](https://officialskills.sh) | Skills from major organizations. |
| [qaskills.sh](https://qaskills.sh) | QA and testing skills. |
## skills.sh leaderboard API
Fetch the all-time ranking programmatically:
```bash
curl 'https://skills.sh/api/skills/all-time/0'
```
Response is `{ skills, total, hasMore, page }`. Pagination is **zero-based**,
**200 skills per page** (`GET /api/skills/all-time/{page}`). Each entry carries
`source`, `skillId`, `name`, `installs`, `weeklyInstalls` (last ~8 weeks), and
`isOfficial`. Verified live 2026-10-19: page 0 returned 200 entries,
`total` 9909, `hasMore` true.
## Install snapshot (2026-10-19, live)
Top 10 by all-time installs, queried from the API above:
| # | Skill | Source | Installs |
|---|-------|--------|----------|
| 1 | `find-skills` | vercel-labs/skills | 3,927,274 |
| 2 | `grill-me` | mattpocock/skills | 1,387,557 |
| 3 | `grill-with-docs` | mattpocock/skills | 1,188,473 |
| 4 | `agent-browser` | vercel-labs/agent-browser | 1,170,738 |
| 5 | `improve-codebase-architecture` | mattpocock/skills | 1,133,991 |
| 6 | `tdd` | mattpocock/skills | 1,110,148 |
| 7 | `hyperframes-cli` | heygen-com/hyperframes | 1,109,284 |
| 8 | `hyperframes` | heygen-com/hyperframes | 1,063,942 |
| 9 | `setup-matt-pocock-skills` | mattpocock/skills | 1,024,734 |
| 10 | `handoff` | mattpocock/skills | 1,008,869 |
`mattpocock/skills` dominates the workflow/design middle of the board; a single
`find-skills` out-installs the next several combined. Vendor suites (Lark, Azure)
that filled ranks 12-50 in the 2026-08-12 snapshot have since dropped out of the
head, so this page keeps only a live top-10 rather than a full 50-row table that
rots between queries. Re-query the API above for a current census.
## Repositories
- [vercel-labs/skills](https://github.com/vercel-labs/skills) — the CLI.
- [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) — reference skills.
- [anthropics/skills](https://github.com/anthropics/skills) — Anthropic's skill set.
- [openai/skills](https://github.com/openai/skills) — OpenAI's skill set.
## See Also
- [The Agent Skills Standard](/skills/agent-skills.md)
- [Skills CLI](/skills/skills-cli.md)
- [Skill Store Wiring](/skills/store-wiring.md)
omp-docs/skills/index.md
+8 -5
View File
@@ -1,11 +1,14 @@
# Skills Documentation
Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system.
The open agent-skills ecosystem as the fleet uses it: the standard, the
installer CLI, this fleet's provisioning tiers, and the registries.
## Concept Files
| File | Type | Description |
|------|------|-------------|
| [npx-skills.md](npx-skills.md) | reference | Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure and the pi-package system |
| [vercel-skills.md](vercel-skills.md) | reference | The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents |
* [The Agent Skills Standard](agent-skills.md) — SKILL.md format, frontmatter fields, loading model, authoring practice, skills vs extensions.
* [Skills CLI](skills-cli.md) — `npx skills`: commands, sources, scopes, discovery, lock file, agent registry.
* [Skill Store Wiring](store-wiring.md) — the three skill tiers on Dank workstations and how omp loads them.
* [Skills Ecosystem](ecosystem.md) — registries, the skills.sh leaderboard API, live install snapshot.
Pi-era skill packaging (`pi install npm:...`, the `pi` package manifest) is
archived under [pi](/pi/index.md).
omp-docs/skills/npx-skills.md
-164
View File
@@ -1,164 +0,0 @@
---
type: reference
title: Npx Skills — Distribution and Installation Patterns
description: Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system.
tags:
- skills
- npm
- agent-skills
- distribution
- pi-package
- unverified
timestamp: 2026-08-28
---
# Npx Skills — Distribution and Installation
In the pi coding agent ecosystem, **"npx skills"** refers to the distribution and installation pattern for agent skills through npm packages. Skills are the content (SKILL.md + scripts); pi packages are the delivery mechanism (npm tarball with a `pi` manifest).
---
## The Two-Layer Model
```
npm package (tagged pi-package)
├── pi.skills manifest → points to ./skills/
└── skills/
├── brave-search/SKILL.md
├── browser-tools/SKILL.md
└── tdd-workflow/SKILL.md
```
---
## The Agent Skills Specification
Pi implements the [Agent Skills standard](https://agentskills.io), which defines:
- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields
- A **Markdown body** with the skill's instructions
- Optional subdirectories: `scripts/`, `references/`, `assets/`
The specification is **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and others.
---
## How Skills Work in Pi
1. **At startup**, pi scans all configured skill locations and extracts skill names and descriptions
2. **The system prompt** includes available skills in XML format
3. **When a task matches**, the agent uses `read` to load the full SKILL.md
4. **The agent follows the instructions**, using relative paths to reference scripts and assets
This is **progressive disclosure**: only descriptions are always in context, full instructions load on-demand.
---
## Installing Skills via NPM / Npx
### Method 1: Direct `pi install` (recommended)
```bash
pi install npm:pi-web-access
pi install npm:@anton-kochev/pi-skills
pi install npm:bigpowers
pi install npm:@monopi/skills
```
### Method 2: Npx-based setup tools
```bash
npx @monopi/monopi # One-command setup
npx @monopi/monopi --version 0.2.13 # Pin a version
npx @monopi/monopi --local # Project-local install
```
### Method 3: Manual clone (git repos)
```bash
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
```
---
## Pi Packages
### Package Structure
```
my-pi-package/
├── package.json # npm metadata + pi manifest
├── skills/ # Conventional directory (auto-discovered)
│ ├── my-skill/
│ │ └── SKILL.md
├── extensions/ # TypeScript extensions
├── prompts/ # Prompt templates
└── themes/ # TUI themes
```
### package.json with pi Manifest
```json
{
"name": "my-pi-package",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"]
}
}
```
### Package Sources
| Source Type | Example | Notes |
|-------------|---------|-------|
| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` |
| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` |
| **local** | `./relative/path` | Points to local directory, added without copying |
---
## SKILL.md Frontmatter
| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. |
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. |
| `license` | No | License name or reference to bundled file. |
| `compatibility` | No | Max 500 chars. Environment requirements. |
| `metadata` | No | Arbitrary key-value mapping. |
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. |
**The description determines when the agent loads the skill. Be specific.**
---
## Discovery Rules
| Location | Scope | Rule |
|----------|-------|------|
| `~/.pi/agent/skills/` | All projects | Direct root `.md` files + directories with `SKILL.md` |
| `.pi/skills/` | Current project | Direct root `.md` files + directories with `SKILL.md` |
| `~/.agents/skills/` | All projects | Only directories with `SKILL.md` (root `.md` ignored) |
---
## Skills vs Extensions
| Feature | Skills | Extensions |
|---------|--------|------------|
| **Format** | Markdown (`SKILL.md`) | TypeScript (`.ts`) |
| **Purpose** | Instructions for the LLM | Code that intercepts events |
| **Execution** | Agent reads and follows | Runs in pi's Node.js runtime |
| **Loading** | On-demand | Always loaded at startup |
---
## Cross-References
- See [Vercel `skills` CLI](vercel-skills.md) for the meta-installer tool.
- The [Agent Skills specification](https://agentskills.io/specification) is the canonical format.
omp-docs/skills/skills-cli.md
+127
View File
@@ -0,0 +1,127 @@
---
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)
omp-docs/skills/store-wiring.md
+62
View File
@@ -0,0 +1,62 @@
---
type: reference
title: omp Skill Store Wiring
description: Division of skill tiers on Dank workstations — skills CLI global store, omp agents provider, and the authored repo tier.
tags:
- skills
- provisioning
- dotfiles
timestamp: 2026-10-18
verified: 2026-10-18
---
# omp Skill Store Wiring
Three tiers, one owner each:
| Tier | Path | Owner | Content |
|---|---|---|---|
| Canonical store | `~/.agents/skills/` | `skills` CLI | upstream skills, 38 as of 2026-10-18 (all `mattpocock/skills`) |
| Provenance | `~/.agents/.skill-lock.json` | `skills` CLI | v3 lockfile: `source`, `skillPath`, `skillFolderHash` per skill |
| Authored | `agent/skills/` (this repo) | Frank, via PR | hand-customized overrides; today only `grilling` |
## How omp loads them
omp is NOT a registered agent in the `skills` CLI (79-agent registry checked
2026-10-18; see [Skills CLI](/skills/skills-cli.md)) —
`skills add` never writes anywhere under `~/.omp`. Instead omp's own `agents`
provider reads the store **directly**: `skills.enableAgentsUser` (default true)
loads `~/.agents/skills/*/SKILL.md`. No per-skill symlinks in the repo — the
repo does not mirror the store; it only holds authored overrides.
Precedence (omp `omp://skills.md`): authored `agent/skills/` (native, priority
100) beats the agents provider; identical copies collapse by realpath, differing
same-named copies survive namespaced (`agents/<name>`) with a startup warning.
Therefore: **when authoring an override, remove the skill from the store**
(`npx skills remove <name> -g`) so the lockfile stays truthful and no
namespaced twin haunts the listing. `grilling` was extracted this way 2026-10-18.
## Updating upstream skills
```bash
npx -y skills update -g # refreshes everything the lockfile tracks
npx skills check # drift report vs GitHub tree SHAs
```
Fresh workstation (omp side is two commands — store restore + authored tier
arrives with the repo clone):
```bash
npx -y skills add mattpocock/skills --all -g
npx -y skills add vercel-labs/skills --skill find-skills --agent universal -g
npx -y skills remove grilling -g # authored copy ships in the repo
```
## Managed tier
`agent/managed-skills/` (auto-learn, priority 5) is separate and untouched by
all of the above; authored skills always win name collisions against it.
## Related
* [Skills CLI](/skills/skills-cli.md) — lock file, update checking, and the full agent registry
omp-docs/skills/vercel-skills.md
-166
View File
@@ -1,166 +0,0 @@
---
type: reference
title: Vercel Labs `skills` CLI
description: The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents with add/use/find/list/update/remove commands.
tags:
- skills
- vercel
- meta-installer
- cross-agent
- cli
- unverified
timestamp: 2026-08-28
---
# Vercel Labs `skills` CLI
`skills` is the CLI for the open agent skills ecosystem, created by Gunnar (@rauchg) at Vercel. It is a **meta-installer** that downloads skills from repositories and installs them into 68+ supported coding agents' skill directories.
**Repository:** [vercel-labs/skills](https://github.com/vercel-labs/skills)
**Specification:** [Agent Skills](https://agentskills.io)
---
## Installation
No global installation needed — run directly via `npx`:
```bash
npx skills add vercel-labs/agent-skills # Install from GitHub
npx skills add vercel-labs/agent-skills --list # List without installing
npx skills use vercel-labs/agent-skills@skill-name # Use without installing
npx skills find typescript # Search
```
---
## Commands
### `skills add` — Install Skills
```bash
npx skills add <source> [options]
```
| Option | Description |
|--------|-------------|
| `-g, --global` | Install to user directory (`~/`) |
| `-a, --agent <agents...>` | Target specific agents |
| `-s, --skill <skills...>` | Install specific skills (use `'*'` for all) |
| `-l, --list` | List available skills |
| `--copy` | Copy files instead of symlinking |
| `-y, --yes` | Skip confirmation prompts |
| `--all` | Install all to all agents |
### `skills use` — Use Without Installing
```bash
npx skills use <source> [options]
# Generates prompt to stdout, or launches agent with --agent
```
### `skills list` (alias: `ls`)
```bash
npx skills list # All installed skills
npx skills ls -g # Global only
```
### `skills find` — Search
```bash
npx skills find # Interactive search
npx skills find typescript # By keyword
```
### `skills update`
```bash
npx skills update # Update all (interactive)
npx skills update -g # Global only
npx skills update -y # Auto-detect scope
```
### `skills remove` (alias: `rm`)
```bash
npx skills remove # Interactive
npx skills remove my-skill -a claude-code -g
npx skills remove --all # Remove everything
```
### `skills init` — Create Template
```bash
npx skills init # Current directory
npx skills init my-skill # Subdirectory
```
---
## Source Formats
```bash
npx skills add owner/repo # GitHub shorthand
npx skills add https://github.com/owner/repo # Full URL
npx skills add https://gitlab.com/org/repo # GitLab
npx skills add git@github.com:owner/repo.git # Git URL
npx skills add ./my-local-skills # Local path
```
---
## Installation Scope
| Scope | Flag | Location | Use Case |
|-------|------|----------|----------|
| **Project** | _(default)_ | `./<agent>/skills/` | Committed with project |
| **Global** | `-g` | `~/<agent>/skills/` | All projects |
Symlink (recommended) or copy mode.
---
## Agent Support
The CLI supports **68+ agents**. Key ones:
| Agent | `--agent` | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
Full table available in the [source repository](https://github.com/vercel-labs/skills).
---
## Lock File System
| Type | Path | Scope |
|------|------|-------|
| **Global lock** | `~/.agents/.skill-lock.json` | User-wide |
| **Local lock** | `skills-lock.json` | Project (check in) |
`skills check` compares GitHub tree SHA with the lock file. `skills update` reinstalls changed skills.
---
## Environment Variables
| Variable | Description |
|----------|-------------|
| `INSTALL_INTERNAL_SKILLS` | Set to `1` to show skills marked `internal: true` |
| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry |
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
---
## Cross-References
- See [Npx Skills](npx-skills.md) for the pi-specific npm package distribution system.
- The [Agent Skills specification](https://agentskills.io/specification) is the shared standard.