dank/command-center
1
0
Fork 0
Code Issues 5 Pull Requests 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
2026-10-19 02:58:52 -07:00
parent e86e60af39
commit 651924a4bc
41 changed files with 439 additions and 1686 deletions
Download Patch File Download Diff File Expand all files Collapse all files
omp-docs/core/index-doc.md
-75
View File
@@ -1,75 +0,0 @@
---
type: reference
title: AGENTS.md Index
description: Overview of the cached tool documentation system — how it works, why the pre-flight check matters, and how to add new entries.
tags:
- documentation
- index
- pre-flight-check
- meta
timestamp: 2026-01-15
---
# pi Documentation Index
This directory (`/home/dank/.pi/agent/docs/`) contains cached documentation for tools used during system configuration. It is the agent's primary reference before touching any configuration file.
---
## How to Use
Before configuring any tool, check whether documentation already exists here. If it does not, a subagent **must** be spawned to fetch documentation before proceeding.
This is not a suggestion. It is the difference between "I remember how to configure this" and "I will need to re-read the docs for the third time this week."
---
## Available Tool Documentation
### Core
* [AGENTS.md Format](agents-md-format.md) — Structure specification for the system-level instruction file: layer conventions, naming, summary table format, and add/remove procedures.
### Tools
* [Ghostty Terminal](../tools/ghostty/index.md) — GPU-accelerated terminal emulator. Complete configuration reference with 100+ options organized by category, CLI actions, keybindings, shaders, and default bindings.
* [llama.cpp Server](../tools/llama-cpp/index.md) — LLM inference server. GGUF format, build guides (CPU/CUDA/Metal/Vulkan), server CLI options, API endpoints, Docker setup, and curl examples.
* [Linux Power Management](../tools/linux-power-management.md) — Systemd sleep configuration, kernel sleep states, NVIDIA GPU suspend/resume, diagnostic tools, kernel parameters, and automated testing procedures.
* [Niri](../tools/niri/index.md) — Scrollable-tiling Wayland compositor. Full keybind cheat sheet, configuration syntax, window management, workspace navigation, and action reference.
### Pi Packages
* [pi-browser-use](../packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, vision model setup, and tool augmentation docs.
* [pi-permission-system](../packages/pi-permission-system.md) — 10 docs covering permission enforcement, config reference, session approvals, cross-extension API, subagent integration, troubleshooting, and migration guides.
### Skills
* [Npx Skills](../skills/npx-skills.md) — Distribution and installation patterns for agent skills via npm, package structure, SKILL.md frontmatter, discovery rules, and the Agent Skills specification.
* [Vercel Labs `skills` CLI](../skills/vercel-skills.md) — CLI meta-installer for cross-agent skill distribution, supporting 68+ agents, with add/use/find/list/update/remove commands.
### References
* [OKF v0.1 Specification](../references/okf-spec.md) — Complete specification for OKF knowledge bundles: bundle structure, frontmatter fields, concept documents, index/log files, cross-linking, and conformance rules.
* [OKF Bundle Maintenance](../references/okf-maintenance.md) — Bundle maintenance: log.md format, frontmatter discipline, one-concept-per-file, staleness detection, and automation strategies.
---
## Adding New Tool Documentation
When a subagent fetches documentation for a new tool:
1. Save it to `tools/<tool-name>/index.md` (multi-file) or `tools/<tool-name>.md` (small, single-concept).
2. Add an entry to this index table.
3. Include a brief description of what the document covers.
4. Add YAML frontmatter with `type` and `description`.
5. Update `log.md` with the change.
---
## Index Format
Give each row this content:
- **Tool** — the tool or technology name
- **File / Path** — relative path within this directory
- **Status** — for example, "Complete", "Partial", "Needs Update"
omp-docs/core/index.md
-1
View File
@@ -11,7 +11,6 @@ These files define the structural conventions that govern the agent system itsel
## Concept Files
* [AGENTS.md Format Specification](agents-md-format.md) — Canonical structure and conventions for the system-level instruction file that governs agent behavior.
* [AGENTS.md Index](index-doc.md) — Overview of the cached tool documentation system and how to add new entries.
* [Pi Settings System](settings.md) — pi-era `settings.json` record (archive): providers, models, packages, subagent overrides.
* [dankvoice](dankvoice.md) — Cloned-voice vocalization extension: `/say` and auto-speak over frank-tts, endpoint read from `agent/models.yml`.
omp-docs/engineering/agents-files.md
+1 -1
View File
@@ -97,4 +97,4 @@ Distribute skills through npm packages with a `pi` manifest, or through the `ski
## See Also
* [SDLC and Tooling](sdlc.md)
* [Skills Ecosystem](skills-ecosystem.md)
* [Skills Ecosystem](/skills/ecosystem.md)
omp-docs/engineering/index.md
+1 -1
View File
@@ -11,7 +11,7 @@ This area distills grounded research into an OKF knowledge bundle. Each page cov
* [Language and Framework Stacks](languages/index.md) - Node/JavaScript, React, Python, Rust, Go.
* [Infrastructure and Cloud](infra/index.md) - Terraform/OpenTofu, containers, Kubernetes, AWS, DigitalOcean, Hetzner.
* [Pi Plugins](plugins.md) - The pi extension ecosystem and notable packages.
* [Skills Ecosystem](skills-ecosystem.md) - skills.sh registry and the top skills.
* [Skills Ecosystem](/skills/ecosystem.md) - skills.sh registry and the live install leaderboard.
* [Signal Remote Control](signal-remote.md) - Drive a pi instance from Signal messages.
## Conventions
omp-docs/engineering/plugins.md
+1 -1
View File
@@ -38,7 +38,7 @@ Some package names that appear in older documentation, such as `pi-browser-use`
## Related Ecosystem
Pi implements the open Agent Skills standard. This makes pi skills compatible with Claude Code, Codex CLI, Amp, Droid, Cursor, and many other agents. See the [Skills Ecosystem](skills-ecosystem.md) page.
Pi implements the open Agent Skills standard. This makes pi skills compatible with Claude Code, Codex CLI, Amp, Droid, Cursor, and many other agents. See the [Skills Ecosystem](/skills/ecosystem.md) page.
## Citations
omp-docs/engineering/skills-ecosystem.md
-144
View File
@@ -1,144 +0,0 @@
---
type: reference
title: Skills Ecosystem and Top Skills
description: The skills.sh registry, the Agent Skills ecosystem, and the verified top 50 skills by installs.
tags:
- skills
- skills-sh
- agent-skills
- ecosystem
- engineering
- unverified
---
verified: 2026-08-28
# Skills Ecosystem and Top Skills
This page covers the open agent skills ecosystem. It describes the registries, the install tooling, and the top skills by category.
## The Ecosystem
`skills.sh` is the primary registry and leaderboard for agent skills. It runs on the open-source `skills` CLI from Vercel Labs. Use these commands:
```bash
npx skills add <owner/repo> # Install skills
npx skills find [query] # Search skills
npx skills list # List installed skills
```
The underlying standard is the Agent Skills specification at [agentskills.io](https://agentskills.io). Over 20 coding agents support it. A single `SKILL.md` works across these agents.
Related registries:
| Registry | Focus |
|----------|-------|
| skills.sh | Primary registry and leaderboard. |
| agentskill.sh | Directory and marketplace with many indexed skills. |
| officialskills.sh | Verified skills from major organizations. |
| qaskills.sh | QA and testing skills. |
Use the local `npx skills` command to explore what is available. You can query the leaderboard data directly at `GET /api/skills/all-time/{page}` on skills.sh. The page index is zero-based and returns 200 skills per page.
## Top 50 Skills by All-Time Installs
The table lists the top 50 skills verified from the live skills.sh API on 2026-08-12. Install counts are exact at query time.
| # | Skill | Source | Installs |
|----|-------|--------|----------|
| 1 | `find-skills` | vercel-labs/skills | 2,918,155 |
| 2 | `grill-me` | mattpocock/skills | 832,797 |
| 3 | `frontend-design` | anthropics/skills | 767,871 |
| 4 | `grill-with-docs` | mattpocock/skills | 708,703 |
| 5 | `improve-codebase-architecture` | mattpocock/skills | 683,652 |
| 6 | `tdd` | mattpocock/skills | 660,660 |
| 7 | `agent-browser` | vercel-labs/agent-browser | 659,465 |
| 8 | `vercel-react-best-practices` | vercel-labs/agent-skills | 625,739 |
| 9 | `setup-matt-pocock-skills` | mattpocock/skills | 607,703 |
| 10 | `handoff` | mattpocock/skills | 570,592 |
| 11 | `triage` | mattpocock/skills | 568,784 |
| 12 | `lark-doc` | open.feishu.cn | 561,794 |
| 13 | `lark-approval` | open.feishu.cn | 561,758 |
| 14 | `lark-base` | open.feishu.cn | 561,634 |
| 15 | `lark-drive` | open.feishu.cn | 561,452 |
| 16 | `lark-shared` | open.feishu.cn | 561,337 |
| 17 | `lark-calendar` | open.feishu.cn | 561,273 |
| 18 | `lark-im` | open.feishu.cn | 561,248 |
| 19 | `lark-contact` | open.feishu.cn | 561,157 |
| 20 | `lark-sheets` | open.feishu.cn | 561,006 |
| 21 | `lark-wiki` | open.feishu.cn | 560,924 |
| 22 | `lark-attendance` | open.feishu.cn | 560,891 |
| 23 | `lark-event` | open.feishu.cn | 560,888 |
| 24 | `lark-minutes` | open.feishu.cn | 560,818 |
| 25 | `lark-openapi-explorer` | open.feishu.cn | 560,777 |
| 26 | `lark-whiteboard` | open.feishu.cn | 560,768 |
| 27 | `lark-mail` | open.feishu.cn | 560,720 |
| 28 | `lark-task` | open.feishu.cn | 560,692 |
| 29 | `lark-slides` | open.feishu.cn | 560,590 |
| 30 | `lark-skill-maker` | open.feishu.cn | 560,554 |
| 31 | `lark-vc` | open.feishu.cn | 560,466 |
| 32 | `lark-workflow-meeting-summary` | open.feishu.cn | 560,368 |
| 33 | `lark-workflow-standup-report` | open.feishu.cn | 560,358 |
| 34 | `prototype` | mattpocock/skills | 556,403 |
| 35 | `lark-okr` | open.feishu.cn | 541,430 |
| 36 | `web-design-guidelines` | vercel-labs/agent-skills | 535,426 |
| 37 | `lark-markdown` | open.feishu.cn | 526,555 |
| 38 | `microsoft-foundry` | microsoft/azure-skills | 523,287 |
| 39 | `azure-diagnostics` | microsoft/azure-skills | 518,052 |
| 40 | `azure-ai` | microsoft/azure-skills | 517,867 |
| 41 | `azure-deploy` | microsoft/azure-skills | 517,694 |
| 42 | `azure-prepare` | microsoft/azure-skills | 517,512 |
| 43 | `azure-validate` | microsoft/azure-skills | 517,228 |
| 44 | `azure-storage` | microsoft/azure-skills | 516,821 |
| 45 | `entra-app-registration` | microsoft/azure-skills | 516,567 |
| 46 | `appinsights-instrumentation` | microsoft/azure-skills | 516,335 |
| 47 | `azure-resource-lookup` | microsoft/azure-skills | 516,249 |
| 48 | `azure-compliance` | microsoft/azure-skills | 516,198 |
| 49 | `azure-aigateway` | microsoft/azure-skills | 516,058 |
| 50 | `azure-kusto` | microsoft/azure-skills | 515,980 |
## Notable Categories
The top 50 breaks down into these groups:
* Development workflow: find-skills, grill-me, tdd, handoff, triage, prototype.
* Design and frontend: frontend-design, vercel-react-best-practices, web-design-guidelines.
* Lark office suite: 22 skills from open.feishu.cn, roughly ranks 12-35.
* Azure infrastructure: 13 skills from microsoft/azure-skills, ranks 38-50.
* Agent orchestration: agent-browser, setup-matt-pocock-skills.
`find-skills` leads by a wide margin with 2.9 million installs. The Lark suite and Azure suite dominate the middle of the list.
## SKILL.md Format
A skill is a directory that contains a `SKILL.md` file:
```yaml
---
name: my-skill
description: What this skill does
---
```
The `name` field is required and lowercase. The `description` field is required. Skills load progressively: discovery loads only the metadata, activation loads the full file on match.
## 2025/2026 Trends
* The Agent Skills spec is the common standard across 20+ agents.
* Skills are write once, use everywhere.
* Registries add security audits for skill content.
* Specialized registries, such as QA, are emerging.
## Citations
* [skills.sh](https://skills.sh)
* [skills.sh API `/api/skills/all-time/0`](https://skills.sh/api/skills/all-time/0)
* [vercel-labs/skills](https://github.com/vercel-labs/skills)
* [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
* [agentskills.io](https://agentskills.io)
* [openai/skills](https://github.com/openai/skills)
## See Also
* [Agent Instruction Files](agents-files.md)
* [Pi Plugins](plugins.md)
* [Skills Documentation](../skills/index.md)
omp-docs/packages/index.md
+1 -1
View File
@@ -12,4 +12,4 @@ Self-contained extensions and tools bundled as npm packages, distributed via the
## Cross-References
- All packages are installed via `pi install npm:<name>` and loaded by pi's extension system.
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution mechanism and package.json manifest format.
- The pi-package distribution mechanism and package.json manifest format are superseded; see [Skills](../skills/index.md).
omp-docs/packages/pi-browser-use.md
+1 -1
View File
@@ -113,5 +113,5 @@ Resolves API key and base URL from the model registry automatically.
## Cross-References
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
- See [Skills](../skills/index.md) for the skill toolchain that replaced pi-package distribution.
- See [OKF Specification](../references/okf-spec.md) for the knowledge bundle format.
omp-docs/packages/pi-permission-system.md
+1 -1
View File
@@ -33,5 +33,5 @@ timestamp: 2026-08-28
## Cross-References
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
- See [Skills](../skills/index.md) for the skill toolchain that replaced pi-package distribution.
- See [AGENTS.md Format](../core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts.
omp-docs/pi/skills.md
+1 -1
View File
@@ -44,4 +44,4 @@ Agent skills teach the agent new workflows. Skills are stored in `~/.pi/agent/sk
## See Also
- [pi](index.md) — Pi configuration overview
- [[npx-skills|npx-skills]] — Skill distribution via npm
- [Skills documentation](../skills/index.md) — the standard, CLI, and store wiring (current harness)
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/tools/vercel-labs-skills/skill-store-wiring.md → omp-docs/skills/store-wiring.md
+2 -3
View File
@@ -23,7 +23,7 @@ Three tiers, one owner each:
## How omp loads them
omp is NOT a registered agent in the `skills` CLI (79-agent registry checked
2026-10-18; see [Agent Support](/tools/vercel-labs-skills/agent-support.md)) —
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
@@ -59,5 +59,4 @@ all of the above; authored skills always win name collisions against it.
## Related
* [Lock File](/tools/vercel-labs-skills/lock-file.md) — hash-based update checking
* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — full CLI agent registry
* [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.
omp-docs/tools/index.md
+6 -17
View File
@@ -10,17 +10,17 @@ Configuration guides and reference material for installed software. Each tool ha
* [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed.
* [live-sync](live-sync.md) — Heartbeat daemon committing machine-written paths (memories, managed-skills, live config, dotfiles) in the command-center checkout; systemd user timer, alerts via ntfy.
* [[applications|applications]] — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
* ](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
* ](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
* ](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
* [ghostty](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
* [gitea](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
* [llama.cpp](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
* [[linux-power-management|linux-power-management]] — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
* [[noctalia-shell|noctalia-shell]] — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
* [handy](handy.md) — Offline speech-to-text transcription with WebKitGTK backend and Tauri v2 UI.
* [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for the workstation.
* [npx Skills](npx-skills/index.md) — Distribution and installation tips for pi skill packages on npm, ecosystem overview, and skill specification.
* [ornith-llama-cpp-setup](ornith-llama-cpp-setup/index.md) — Setup and reference for running Ornith MoE models with llama.cpp server for local inference.
* [[tmux|tmux]] — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
* ](vercel-labs-skills/index.md) — Complete list of 68+ supported coding agents, their --agent flags, installation paths, and the SKILL.md specification.
## Adding a New Tool
@@ -28,16 +28,5 @@ Configuration guides and reference material for installed software. Each tool ha
2. Add `index.md` as the entry point (no frontmatter for directory listings)
3. Create concept files with frontmatter if content exceeds one file
4. Update this index
5. Log the change in `log.md`
* [Default Applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
* [CachyOS](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation.
* [Linux Power Management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
* [Noctalia Shell](noctalia-shell.md) — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
* [Handy](handy.md) — Offline speech-to-text transcription with WebKitGTK backend and Tauri v2 UI.
* [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
Skills tooling lives in [/skills/](../skills/index.md), not in this directory.
omp-docs/tools/niri/screenshots.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
type: reference
title: Screenshot Matrix
description: Screenshot setup on blankpad — flameshot retired (all modes hang via portal on 2+ outputs, niri#4313); niri-native binds: all-monitors script, focused-screen capture, interactive UI. Includes the niri spawn-sh PATH trap.
description: "Screenshot setup on blankpad — flameshot retired (all modes hang via portal on 2+ outputs, niri#4313); niri-native binds: all-monitors script, focused-screen capture, interactive UI. Includes the niri spawn-sh PATH trap."
tags:
- niri
- flameshot
omp-docs/tools/npx-skills/best-practices.md
-48
View File
@@ -1,48 +0,0 @@
---
type: guide
title: Skill Author Best Practices
description: Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
tags:
- unverified
- skills
- best-practices
- authoring
timestamp: 2026-07-18
verified: 2026-08-28
---
# Best Practices for Skill Authors
## Description Writing
1. **Be specific about capabilities** — "Extracts text and tables from PDF files, fills forms, merges documents" vs "Helps with documents"
2. **Include trigger phrases** — "Use when working with PDF files or when user mentions PDFs, forms, or document extraction"
3. **Keep under 1024 characters**
4. **Write in third person**
5. **First sentence = what it does, second sentence = when to use it**
## File Organization
1. **Use progressive disclosure** — Keep SKILL.md focused; reference detailed docs in `references/`
2. **Add scripts for deterministic operations** — When the same code would be generated repeatedly, scripts save tokens and improve reliability
3. **Split files when content exceeds ~500 lines** — Agents load the entire file on activation
4. **Include a config.json** for configurable paths or settings
5. **Add tests** — Include test scripts and mock data for validation
## Security
1. **Review skill content before use** — Skills can instruct the model to perform any action
2. **Scripts run with your full system permissions** — Only install from trusted sources
3. **Document dependencies clearly** — List all required tools, API keys, and setup steps
## Distribution
1. **Add `pi-package` keyword** to package.json for npm discoverability
2. **Include `video` or `image` fields** in the pi manifest for the gallery
3. **Use peerDependencies** for pi-provided packages: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `typebox`
4. **List runtime deps in `dependencies`** — They get installed automatically
## Related
* [Package Structure](/tools/npx-skills/package-structure.md) — How to structure your npm package
* [Installation](/tools/npx-skills/installation.md) — How users will install your skills
omp-docs/tools/npx-skills/ecosystem.md
-62
View File
@@ -1,62 +0,0 @@
---
type: reference
title: Ecosystem Resources
description: GitHub repositories, npm packages, and community resources for the pi skills ecosystem.
tags:
- unverified
- ecosystem
- npm
- repositories
- community
timestamp: 2026-07-18
verified: 2026-08-28
---
# Ecosystem Resources
## Official Documentation
- [Pi Skills Documentation](https://github.com/earendil-works/pi)
- [Pi Packages Documentation](https://github.com/earendil-works/pi)
- [Agent Skills Specification](https://agentskills.io/specification)
- [Agent Skills Integration Guide](https://agentskills.io/integrate-skills)
- [Pi Packages Gallery](https://pi.dev/packages)
## GitHub Repositories
| Repository | Description | Stars |
|------------|-------------|-------|
| [badlogic/pi-skills](https://github.com/badlogic/pi-skills) | Official skills collection (brave-search, browser-tools, Google APIs, transcription) | 2,138 |
| [ifiokjr/monopi](https://github.com/ifiokjr/monopi) | One-click pi setup with skills, extensions, themes, subagents | 136 |
| [VenTheZone/pi-dots](https://github.com/VenTheZone/pi-dots) | 60+ skills covering research, content, project management, debugging | 42 |
| [HazAT/pi-config](https://github.com/HazAT/pi-config) | Personal pi config with skills, extensions, agents | 418 |
| [qualisero/awesome-pi-agent](https://github.com/qualisero/awesome-pi-agent) | Awesome list of pi add-ons, hooks, tools, skills | 1,093 |
| [getpipher/pi-package-index](https://github.com/getpipher/pi-package-index) | Unofficial community index with GitHub stars + downloads | 2 |
| [lukaspanni/pi-package-template](https://github.com/lukaspanni/pi-package-template) | Template for creating pi packages | 0 |
## Notable npm Packages
| Package | Description | Keywords |
|---------|-------------|----------|
| `pi-web-access` | Web search, URL fetching, PDF extraction, YouTube analysis | pi-package, web-search, perplexity |
| `@wierdbytes/pi-peon` | Sound-pack player for pi (installed) | pi-package, peon, sound |
| `bigpowers` | 73 agent skills for solo developers | skills, agents, claude, pi-package |
| `pi-spark` | Polishes daily pi experience | pi-coding-agent, pi-package |
| `@anton-kochev/pi-skills` | Planning, TDD, SRS, requirements skills | pi-package, pi-skill, tdd |
| `@monopi/skills` | Curated skill packs (debug-helper, btw, nushell) | pi-package, skills |
| `@dietrichgebert/ponytail` | Lazy senior dev mode with skills | opencode, pi-package, skills |
| `pi-mcp-adapter` | MCP adapter for pi | pi-package, mcp |
| `pi-subagents` | Subagent delegation with chains | pi-package, subagents |
| `pi-lens` | Real-time code feedback (LSP, linters) | pi-package, linter |
| `@vanillagreen/pi-skills-manager` | Skills manager with /skill menu | pi-package, skills, manager |
## Community Resources
- [pi-package.rectorspace.com](https://pi-package.rectorspace.com) — Unofficial package index with stars, downloads, maintenance signals
- [Anthropic Skills](https://github.com/anthropics/skills) — Document processing skills (docx, pdf, pptx, xlsx)
- [skills.sh](https://skills.sh) — Skills directory (by Vercel Labs)
## Related
* [Installation](/tools/npx-skills/installation.md) — How to install from these resources
* [Best Practices](/tools/npx-skills/best-practices.md) — How to contribute your own skills
omp-docs/tools/npx-skills/index.md
-18
View File
@@ -1,18 +0,0 @@
# Npx Skills — Distribution & Installation
Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
## Concept Files
| File | Type | Description |
|------|------|-------------|
| [best-practices.md](best-practices.md) | best-practices | Tips for writing good skill descriptions, organizing files, and distributing ... |
| [ecosystem.md](ecosystem.md) | reference | GitHub repositories, npm packages, and community resources for the pi skills ... |
| [installation.md](installation.md) | howto | Three methods for installing skills — pi install, npx-based setup tools, and ... |
| [package-structure.md](package-structure.md) | reference | How pi packages bundle skills, extensions, prompts, and themes into a single ... |
| [skill-commands.md](skill-commands.md) | reference | The /skill:name command system for explicitly loading and executing skills wi... |
| [skill-file-structure.md](skill-file-structure.md) | reference | The directory structure of a skill — SKILL.md as the required entry point, wi... |
| [skill-loading.md](skill-loading.md) | reference | The discovery flow, progressive disclosure pattern, and system prompt integra... |
| [skills-spec.md](skills-spec.md) | reference | The Agent Skills standard that defines SKILL.md format, frontmatter fields, a... |
| [skills-vs-extensions.md](skills-vs-extensions.md) | comparison | Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-... |
omp-docs/tools/npx-skills/installation.md
-81
View File
@@ -1,81 +0,0 @@
---
type: howto
title: Installing Skills via npm / npx
description: Three methods for installing skills — pi install, npx-based setup tools, and manual git clone.
tags:
- unverified
- installation
- npm
- npx
timestamp: 2026-07-18
verified: 2026-08-28
---
# Installing Skills via NPM / Npx
## Method 1: Direct `pi install` (recommended)
```bash
# Install a package containing skills
pi install npm:pi-web-access
pi install npm:@anton-kochev/pi-skills
pi install npm:bigpowers
pi install npm:@monopi/skills
# Install from GitHub (also works for packages with skills)
pi install git:github.com/badlogic/pi-skills
pi install https://github.com/badlogic/pi-skills
# Project-level install (goes to .pi/settings.json)
pi install -l npm:pi-web-access
# Try without installing (current session only)
pi -e npm:pi-web-access
```
## Method 2: Npx-based setup tools
Some meta-installers provide one-command setup:
```bash
# monopi: one-command setup for pi with skills, extensions, themes, etc.
npx @monopi/monopi
# Pin a version
npx @monopi/monopi --version 0.2.13
# Project-local install
npx @monopi/monopi --local
# Remove all monopi packages
npx @monopi/monopi --remove
```
## Method 3: Manual clone (git repos)
```bash
# Clone the official pi-skills collection
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
# Or project-level
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills
```
## 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 |
## Dependencies
- Runtime dependencies belong in `dependencies` in `package.json`
- Pi-provided packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`) as `peerDependencies` with `"*"` range
- When pi installs from npm or git, it runs `npm install` automatically
## Related
* [Package Structure](/tools/npx-skills/package-structure.md) — How pi packages are structured for npm distribution
* [Best Practices](/tools/npx-skills/best-practices.md) — Distribution tips for skill authors
omp-docs/tools/npx-skills/package-structure.md
-79
View File
@@ -1,79 +0,0 @@
---
type: reference
title: Pi Package Structure
description: How pi packages bundle skills, extensions, prompts, and themes into a single npm package with a pi manifest.
tags:
- unverified
- packages
- npm
- distribution
timestamp: 2026-07-18
verified: 2026-08-28
---
# Pi Packages — The Distribution Mechanism
Pi packages are npm packages that declare resources via a `pi` manifest in `package.json`. They are the primary way to distribute skills (along with extensions, prompts, and themes) through npm.
## Package Structure
```
my-pi-package/
├── package.json # npm metadata + pi manifest
├── skills/ # Conventional directory (auto-discovered)
│ ├── my-skill/
│ │ └── SKILL.md
│ └── another-skill/
│ └── SKILL.md
├── extensions/ # TypeScript extensions
├── prompts/ # Prompt templates
├── themes/ # TUI themes
└── README.md
```
## Package.json with pi Manifest
```json
{
"name": "my-pi-package",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"]
}
}
```
## Gallery Metadata
Packages tagged with `pi-package` appear on the [pi.dev/packages gallery](https://pi.dev/packages). Add preview media:
```json
{
"pi": {
"skills": ["./skills"],
"video": "https://example.com/demo.mp4",
"image": "https://example.com/screenshot.png"
}
}
```
## 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
```
Skills are the **content** (SKILL.md + scripts). Pi packages are the **delivery mechanism** (npm tarball with a `pi` manifest).
## Related
* [Installation](/tools/npx-skills/installation.md) — How to install pi packages
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — What goes inside a skill
omp-docs/tools/npx-skills/skill-commands.md
-35
View File
@@ -1,35 +0,0 @@
---
type: reference
title: Skill Commands
description: The /skill:name command system for explicitly loading and executing skills with optional arguments.
tags:
- unverified
- skills
- commands
timestamp: 2026-07-18
verified: 2026-08-28
---
# Skill Commands (`/skill:name`)
Skills register as `/skill:name` commands:
```bash
/skill:brave-search # Load and execute the skill
/skill:pdf-tools extract # Load skill with arguments
```
Arguments after the command are appended to the skill content as `User: <args>`.
Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
```json
{
"enableSkillCommands": true
}
```
## Related
* [Skill Loading](../npx-skills/skill-loading.md) — How skills are normally loaded
* [Npx Skills Overview](../npx-skills/index.md) — Settings and package control
omp-docs/tools/npx-skills/skill-file-structure.md
-65
View File
@@ -1,65 +0,0 @@
---
type: reference
title: Skill File Structure
description: The directory structure of a skill — SKILL.md as the required entry point, with optional scripts, references, and assets directories.
tags:
- unverified
- skills
- structure
- SKILL.md
timestamp: 2026-07-18
verified: 2026-08-28
---
# Skill File Structure
A skill is a **directory** with a `SKILL.md` file. Everything else is freeform.
## Standard Structure
```
my-skill/
├── SKILL.md # Required: frontmatter + instructions
├── scripts/ # Helper scripts (bash, js, python, etc.)
│ ├── process.sh
│ └── analyze.js
├── references/ # Detailed docs loaded on-demand
│ ├── api-reference.md
│ └── FORMS.md
├── assets/ # Templates, configs, binary data
│ └── template.json
├── config.json # Skill-specific configuration
└── tests/ # Test scripts (optional)
└── test_runner.sh
```
## Real Example: zim-knowledge-base
```
zim-knowledge-base/
├── SKILL.md # Main skill instructions
├── config.json # ZIM file path configuration
├── scripts/
│ ├── search.sh # Search ZIM file index
│ ├── extract.sh # Extract article as HTML
│ ├── list.sh # List article titles
│ └── metadata.sh # Get article metadata
└── tests/
├── mock_zimdump.sh # Mock for testing
├── test_runner.sh # Test harness
└── test_zim_file.zim # Test fixture
```
## Real Example: brave-search (from badlogic/pi-skills)
```
brave-search/
├── SKILL.md # Setup + usage instructions
├── search.js # Brave Search API wrapper
└── content.js # Page content extraction
```
## Related
* [Skills Specification](/tools/npx-skills/skills-spec.md) — Frontmatter fields and requirements
* [Best Practices](/tools/npx-skills/best-practices.md) — File organization tips
omp-docs/tools/npx-skills/skill-loading.md
-42
View File
@@ -1,42 +0,0 @@
---
type: reference
title: How Pi Loads Skills
description: The discovery flow, progressive disclosure pattern, and system prompt integration for skills in pi.
tags:
- unverified
- skills
- loading
- progressive-disclosure
timestamp: 2026-07-18
verified: 2026-08-28
---
# How the Pi Agent Loads and Uses Skills
## Discovery Flow
1. Pi scans all configured skill locations at startup
2. Extracts names and descriptions from each `SKILL.md`
3. Builds the system prompt with skill descriptions in XML format
4. The LLM decides which skill(s) to activate based on the user's prompt
5. When activated, the agent reads the full SKILL.md using the `read` tool
## Progressive Disclosure Pattern
```
System prompt (always in context):
- "Available skills: brave-search (Web search...), browser-tools (Browser automation...), ..."
User: "Search for information about React hooks"
Agent decides: activate brave-search
Agent reads: ~/.pi/agent/skills/brave-search/SKILL.md (full file)
Agent executes: {baseDir}/search.js "React hooks"
```
## This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
## Related
* [Skills Specification](/tools/npx-skills/skills-spec.md) — What the agent sees in the system prompt
* [Skill Commands](/tools/npx-skills/skill-commands.md) — The `/skill:name` override
omp-docs/tools/npx-skills/skills-spec.md
-70
View File
@@ -1,70 +0,0 @@
---
type: reference
title: Agent Skills Specification
description: The Agent Skills standard that defines SKILL.md format, frontmatter fields, and cross-agent compatibility.
tags:
- unverified
- agent-skills
- specification
- npm
timestamp: 2026-07-18
verified: 2026-08-28
---
# Agent Skills Specification
Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. The specification 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 designed to be **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and other compatible agents.
## Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. No leading/trailing hyphens. No consecutive hyphens. |
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. **This is the only thing the agent sees when deciding whether to activate the skill.** |
| `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. Users must use `/skill:name` explicitly. |
### Name Rules
Valid: `pdf-processing`, `data-analysis`, `code-review`
Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
**Note:** Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories.
### Description Best Practices
The description determines when the agent loads the skill. Be specific.
**Good:**
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
```
**Poor:**
```yaml
description: Helps with PDFs.
```
## Cross-Agent Compatibility
Skills follow a shared specification that works across:
- Pi (`~/.pi/agent/skills/`)
- Claude Code (`~/.claude/skills/`)
- Codex (`~/.codex/skills/`)
- OpenCode (`~/.config/opencode/skills/`)
- And [68+ other agents](/tools/vercel-labs-skills/agent-support.md)
## Related
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — How to organize SKILL.md and its supporting files
* [Ecosystem](/tools/npx-skills/ecosystem.md) — Where to find community skills
omp-docs/tools/npx-skills/skills-vs-extensions.md
-50
View File
@@ -1,50 +0,0 @@
---
type: reference
title: Skills vs Extensions
description: Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-based) for pi coding agent.
tags:
- unverified
- skills
- extensions
- comparison
timestamp: 2026-07-18
verified: 2026-08-28
---
# Skills vs Extensions
| Feature | Skills | Extensions |
|---------|--------|------------|
| **Format** | Markdown (`SKILL.md` + optional scripts) | TypeScript (`.ts` files) |
| **Purpose** | Instructions for the LLM to follow | Code that intercepts events, registers tools/commands |
| **Execution** | Agent reads and follows instructions | Runs in pi's Node.js runtime |
| **Loading** | On-demand (progressive disclosure) | Always loaded at startup |
| **Power** | Can instruct the agent to run anything | Full programmatic access to pi's API |
| **Security** | Review content (instructs model) | Review code (runs arbitrary code) |
| **Best for** | Domain knowledge, workflows, scripts | Permission gates, custom tools, event handling |
| **Location** | `skills/` directory | `extensions/` directory |
| **Can distribute via npm?** | Yes (via pi packages) | Yes (via pi packages) |
## When to Use Each
- **Skill**: You want to teach the agent a new workflow, provide domain expertise, or bundle helper scripts
- **Extension**: You need to intercept tool calls, register new LLM-callable tools, modify system prompts programmatically, or add custom TUI components
## They Can Work Together
A pi package can contain both:
```json
{
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"]
}
}
```
Example: `pi-web-access` provides both a web-search extension AND skill documentation for it.
## Related
* [Package Structure](/tools/npx-skills/package-structure.md) — How to bundle both in one npm package
omp-docs/tools/vercel-labs-skills/agent-support.md
-84
View File
@@ -1,84 +0,0 @@
---
type: reference
title: Skills CLI Agent Support Matrix
description: Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
tags:
- unverified
- skills
- agents
- compatibility
timestamp: 2026-07-18
verified: 2026-08-28
---
# Agent Support
The CLI supports **68+ agents**. It automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.
## Full Agent Path Table
| Agent | `--agent` | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
| Cline, Dexto, Kimi Code CLI, Loaf, Warp, Zed | `cline`, `dexto`, `kimi-code-cli`, `loaf`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
| Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
| Droid / Factory AI | `droid` | `.factory/skills/` | `~/.factory/skills/` |
| Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` |
| Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` |
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
| Anthropic Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
| Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` |
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
| Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` |
| Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` |
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
| AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` |
| IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` |
| CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` |
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
| Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` |
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
| Eve | `eve` | `agent/skills/` | N/A (project-only) |
| ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` |
| Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` |
| inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` |
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
| Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` |
| PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) |
| Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` |
| Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` |
| Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` |
| Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` |
| Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` |
| Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` |
> **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no configuration needed.
## Related
* [Commands](/tools/vercel-labs-skills/commands.md) — Using the `--agent` flag with commands
omp-docs/tools/vercel-labs-skills/commands.md
-116
View File
@@ -1,116 +0,0 @@
---
type: reference
title: Skills CLI Commands
description: Complete reference for all skills CLI commands — add, use, list, find, update, remove, init, experimental_install, experimental_sync.
tags:
- unverified
- skills
- cli
- commands
timestamp: 2026-07-18
verified: 2026-08-28
---
# Commands Reference
## `skills add` — Install Skills
Install skills from a source (git repo, URL, or local path) into your agent directories.
```bash
npx skills add <source> [options]
```
### Options
| Option | Description |
|--------|-------------|
| `-g, --global` | Install to user directory (`~/`) instead of project (`./`) |
| `-a, --agent <agents...>` | Target specific agents |
| `-s, --skill <skills...>` | Install specific skills by name. Use `'*'` for all. |
| `-l, --list` | List available skills without installing |
| `--copy` | Copy files instead of symlinking |
| `-y, --yes` | Skip all confirmation prompts |
| `--all` | Install all skills to all agents without prompts |
### Examples
```bash
npx skills add vercel-labs/agent-skills --list
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
npx skills add vercel-labs/agent-skills -a claude-code -a opencode
npx skills add vercel-labs/agent-skills --all
```
## `skills use` — Use Without Installing
Generate a prompt for one skill, or start a supported coding agent interactively with the skill loaded.
```bash
npx skills use <source> [options]
# Generate prompt only
npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
# Use with specific agent
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code
```
## `skills list` (alias: `ls`) — List Installed Skills
```bash
npx skills list
npx skills ls -g # Global only
npx skills ls -a claude-code -a cursor
```
## `skills find` — Search for Skills
```bash
npx skills find # Interactive search
npx skills find typescript # Search by keyword
npx skills find react --owner vercel
```
## `skills update` — Update Installed Skills
```bash
npx skills update # All skills (interactive)
npx skills update my-skill # Single skill
npx skills update -g # Global only
npx skills update -y # Non-interactive
```
## `skills remove` (alias: `rm`) — Remove Installed Skills
```bash
npx skills remove # Interactive
npx skills remove web-design-guidelines
npx skills remove --all # Remove everything
```
## `skills init` — Create a New SKILL.md Template
```bash
npx skills init # In current directory
npx skills init my-skill # In a subdirectory
```
## `skills experimental_install` — Restore from Lock File
```bash
npx skills experimental_install
```
## Aliases
| Alias | Full Command |
|-------|-------------|
| `skills a` | `skills add` |
| `skills i` | `skills experimental_install` |
| `skills install` (no args) | `skills experimental_install` |
| `skills ls` | `skills list` |
| `skills rm` | `skills remove` |
## Related
* [Source Formats](/tools/vercel-labs-skills/source-formats.md) — What sources you can use with add/use
* [Installation Scope](/tools/vercel-labs-skills/installation-scope.md) — Global vs project
omp-docs/tools/vercel-labs-skills/env-variables.md
-33
View File
@@ -1,33 +0,0 @@
---
type: reference
title: Skills CLI Environment Variables
description: Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TRACK.
tags:
- unverified
- skills
- environment
- telemetry
timestamp: 2026-07-18
verified: 2026-08-28
---
# Environment Variables
| Variable | Description |
|----------|-------------|
| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
| `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
```bash
# Install internal skills
INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
```
## Telemetry
The CLI collects anonymous usage data to help improve the tool. No personal information is collected. Telemetry is automatically disabled in CI environments.
## Related
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — `metadata.internal: true`
omp-docs/tools/vercel-labs-skills/index.md
-19
View File
@@ -1,19 +0,0 @@
# Vercel Labs `skills` CLI
Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
## Concept Files
| File | Type | Description |
|------|------|-------------|
| [agent-support.md](agent-support.md) | reference | Complete list of 68+ supported coding agents, their --agent flags, and instal... |
| [commands.md](commands.md) | reference | Complete reference for all skills CLI commands — add, use, list, find, update... |
| [env-variables.md](env-variables.md) | reference | Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TR... |
| [installation-scope.md](installation-scope.md) | reference | Project vs global installation, symlink vs copy methods. |
| [lock-file.md](lock-file.md) | reference | Version pinning and update checking via global and local lock files (.skill-l... |
| [related-links.md](related-links.md) | reference | Links to the Agent Skills specification, skills directory, integration guide,... |
| [skill-discovery.md](skill-discovery.md) | reference | How the skills CLI discovers SKILL.md files in repositories — flat layout, ca... |
| [skill-format.md](skill-format.md) | reference | The required frontmatter fields, optional fields, internal skills, and struct... |
| [skill-store-wiring.md](skill-store-wiring.md) | reference | How omp's agent/skills directory is symlinked into the skills CLI global store, and where lockfile provenance lives. |
| [source-formats.md](source-formats.md) | reference | All accepted source formats for skills add and use — GitHub shorthand, full U... |
omp-docs/tools/vercel-labs-skills/installation-scope.md
-36
View File
@@ -1,36 +0,0 @@
---
type: reference
title: Skills CLI Installation Scope
description: Project vs global installation, symlink vs copy methods.
tags:
- unverified
- skills
- installation
- scope
timestamp: 2026-07-18
verified: 2026-08-28
---
# Installation Scope
## Project vs Global
| Scope | Flag | Location | Use Case |
|-------|------|----------|----------|
| **Project** | _(default)_ | `./<agent>/skills/` | Committed with your project, shared with team |
| **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
## Symlink vs Copy
When installing interactively, you can choose:
| Method | Description |
|--------|-------------|
| **Symlink** _(Recommended)_ | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
| **Copy** | Creates independent copies for each agent. Use when symlinks are not supported. |
Use `--copy` to force copy mode.
## Related
* [Commands](/tools/vercel-labs-skills/commands.md) — add, use, list, remove commands
omp-docs/tools/vercel-labs-skills/lock-file.md
-43
View File
@@ -1,43 +0,0 @@
---
type: reference
title: Skills CLI Lock File System
description: Version pinning and update checking via global and local lock files (.skill-lock.json and skills-lock.json).
tags:
- unverified
- skills
- lockfile
- versioning
timestamp: 2026-07-18
verified: 2026-08-28
---
# Lock File System
The `skills` CLI uses a lock file system for version pinning and update checking.
## Lock File Locations
| Type | Path | Scope |
|------|------|-------|
| **Global lock** | `~/.agents/.skill-lock.json` | Global (user-wide) |
| **Local lock** | `skills-lock.json` | Project (checked into version control) |
## How `skills check` and `skills update` Work
1. Read `~/.agents/.skill-lock.json` for installed skills
2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath`
3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`
- Optional auth token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`
4. `fetchSkillFolderHash` calls GitHub Trees API (`/git/trees/<branch>?recursive=1` for `main`, then `master` fallback)
5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available
6. `skills update` reinstalls changed skills by invoking the current CLI directly
## Lock File Format
- **Version:** v3
- **Key field:** `skillFolderHash` — GitHub tree SHA for the skill folder
- **Compatibility:** If reading an older lock file version, it is wiped. Users must reinstall skills to populate the new format.
## Related
* [Commands](/tools/vercel-labs-skills/commands.md) — check, update, experimental_install
omp-docs/tools/vercel-labs-skills/related-links.md
-43
View File
@@ -1,43 +0,0 @@
---
type: reference
title: Vercel Labs Skills — Related Links
description: Links to the Agent Skills specification, skills directory, integration guide, and agent-specific skill documentation.
tags:
- unverified
- skills
- links
- resources
timestamp: 2026-07-18
verified: 2026-08-28
---
# Related Links
## Specification & Ecosystem
| Resource | URL |
|----------|-----|
| [Agent Skills Specification](https://agentskills.io) | agentskills.io/specification |
| [Skills Directory](https://skills.sh) | skills.sh |
| [Agent Skills Integration Guide](https://agentskills.io/integrate-skills) | agentskills.io/integrate-skills |
| [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills) | github.com/vercel-labs/agent-skills |
## Agent-Specific Skill Documentation
| Agent | Documentation |
|-------|--------------|
| Amp | [Amp Skills Documentation](https://ampcode.com/manual#agent-skills) |
| Claude Code | [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) |
| Codex | [Codex Skills Documentation](https://developers.openai.com/codex/skills) (url unreachable 2026-08-28) |
| Cursor | [Cursor Skills Documentation](https://cursor.com/docs/context/skills) |
| Gemini CLI | [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/) (url unreachable 2026-08-28) |
| GitHub Copilot | [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) |
| OpenCode | [OpenCode Skills Documentation](https://opencode.ai/docs/skills) (url unreachable 2026-08-28) |
| OpenHands | [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills) (url unreachable 2026-08-28) |
| Pi | [Pi Skills Documentation](https://github.com/earendil-works/pi) |
| Roo Code | [Roo Code Skills Documentation](https://docs.roocode.com/features/skills) (url unreachable 2026-08-28) |
| Windsurf | [Windsurf](https://www.codeium.com/windsurf) (url unreachable 2026-08-28) |
## Related
* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — Full list of 68+ supported agents
omp-docs/tools/vercel-labs-skills/skill-discovery.md
-63
View File
@@ -1,63 +0,0 @@
---
type: reference
title: Skills CLI Skill Discovery
description: How the skills CLI discovers SKILL.md files in repositories — flat layout, catalog layout, plugin manifests.
tags:
- unverified
- skills
- discovery
- repository
timestamp: 2026-07-18
verified: 2026-08-28
---
# Skill Discovery
The CLI searches for skills in these locations within a repository. Each skill container directory is walked:
- **One level deep** for the common flat layout: `skills/<name>/SKILL.md`
- **One extra level deep** for catalog layouts: `skills/<category>/<name>/SKILL.md`
A `SKILL.md` discovered at the shallower level shadows anything nested below it. Use `--full-depth` to also discover `SKILL.md` files outside these container directories.
## Standard Discovery Locations
- `SKILL.md` in root directory (if present)
- `skills/`
- `skills/.curated/`
- `skills/.experimental/`
- `skills/.system/`
- `.agents/skills/`
- `.claude/skills/`
- `.goose/skills/`
- `.openhands/skills/`
- `.pi/skills/`
- And many more per-agent directories (see [Agent Support](/tools/vercel-labs-skills/agent-support.md))
## Plugin Manifest Discovery
If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered. This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
Example `marketplace.json`:
```json
{
"metadata": { "pluginRoot": "./plugins" },
"plugins": [
{
"name": "my-plugin",
"source": "my-plugin",
"skills": ["./skills/review", "./skills/test"]
}
]
}
```
Skill paths declared in a manifest are searched at their declared depth.
If no skills are found in standard locations, a **recursive search** is performed as a fallback.
## Related
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — What a discovered skill looks like
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
omp-docs/tools/vercel-labs-skills/skill-format.md
-70
View File
@@ -1,70 +0,0 @@
---
type: reference
title: SKILL.md Format
description: The required frontmatter fields, optional fields, internal skills, and structure for SKILL.md files.
tags:
- skills
- SKILL.md
- format
- unverified
verified: 2026-08-28
# SKILL.md Format
Skills are directories containing a `SKILL.md` file with YAML frontmatter.
## Basic Structure
```markdown
---
name: my-skill
description: What this skill does and when to use it
---
# My Skill
Instructions for the agent to follow when this skill is activated.
## When to Use
Describe the scenarios where this skill is used.
## Steps
1. First, do this
2. Then, do that
```
## Required Frontmatter Fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique identifier (lowercase, hyphens allowed) |
| `description` | string | Brief explanation of what the skill does |
## Optional Frontmatter Fields
| Field | Type | Description |
|-------|------|-------------|
| `metadata.internal` | boolean | Set to `true` to hide the skill from normal discovery. Requires `INSTALL_INTERNAL_SKILLS=1` |
| `license` | string | License name or reference to bundled file |
| `compatibility` | string | Environment requirements (max 500 chars) |
| `metadata` | object | Arbitrary key-value mapping |
| `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental) |
| `disable-model-invocation` | boolean | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly |
## Internal Skills Example
```markdown
---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
internal: true
---
```
## Related
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are discovered in repos
* [Commands](/tools/vercel-labs-skills/commands.md) — `skills init` to create new skills
omp-docs/tools/vercel-labs-skills/source-formats.md
-43
View File
@@ -1,43 +0,0 @@
---
type: reference
title: Skills CLI Source Formats
description: All accepted source formats for skills add and use — GitHub shorthand, full URLs, GitLab, git URLs, local paths.
tags:
- unverified
- skills
- sources
- git
timestamp: 2026-07-18
verified: 2026-08-28
---
# Source Formats
The `skills` CLI accepts multiple source formats for the `add` and `use` commands:
```bash
# GitHub shorthand (owner/repo)
npx skills add vercel-labs/agent-skills
# Full GitHub URL
npx skills add https://github.com/vercel-labs/agent-skills
# Direct path to a skill in a repo
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# GitLab URL
npx skills add https://gitlab.com/org/repo
# Any git URL
npx skills add git@github.com:vercel-labs/agent-skills.git
# Local path
npx skills add ./my-local-skills
```
The source parser (`src/source-parser.ts`) handles all these formats, cloning repos as needed and resolving skill directories.
## Related
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are found within repos
scripts/kb-lint.sh
+14 -3
View File
@@ -7,6 +7,7 @@ KB="$(cd "${1:-omp-docs}" 2>/dev/null && pwd)" || { echo "kb-lint: no such dir:
python3 - "$KB" <<'PY'
import re, sys
import yaml
from pathlib import Path
kb = Path(sys.argv[1])
violations = []
@@ -14,6 +15,7 @@ violations = []
for p in sorted(kb.rglob("*.md")):
rel = p.relative_to(kb)
text = p.read_text(errors="replace")
lines = text.splitlines()
if p.name == "index.md":
# OKF rule: index files are directory listings and carry NO frontmatter.
if text.startswith("---"):
@@ -22,9 +24,18 @@ for p in sorted(kb.rglob("*.md")):
if not text.startswith("---"):
violations.append(f"{rel}: missing frontmatter")
continue
end = text.find("\n---", 3)
fm = text[3:end] if end != -1 else ""
if not re.search(r"^type:", fm, re.M):
# Close the block at the first line that is exactly --- or ...; anything
# else (including fenced `---` deep in the body) is body, not a delimiter.
end = next((i for i in range(1, len(lines)) if lines[i].strip() in ("---", "...")), None)
if end is None:
violations.append(f"{rel}: frontmatter block is not closed (no '---' delimiter line)")
continue
try:
fm = yaml.safe_load("\n".join(lines[1:end])) or {}
except yaml.YAMLError:
violations.append(f"{rel}: frontmatter block is malformed YAML or not closed")
continue
if not isinstance(fm, dict) or not str(fm.get("type", "")).strip():
violations.append(f"{rel}: frontmatter lacks required 'type:'")
# link integrity: fenced code blocks hold example paths, not live links — strip first.
tests/kb-lint.bats
Executable
+92
View File
@@ -0,0 +1,92 @@
#!/usr/bin/env bats
# tests/kb-lint.bats — black-box tests for scripts/kb-lint.sh
#
# Contract: exit 0 when a knowledge bundle is OKF v0.1 conformant;
# one line per violation otherwise. Observable surface: stdout lines
# and exit status only.
setup() {
LINT="$BATS_TEST_DIRNAME/../scripts/kb-lint.sh"
KB="$(mktemp -d)/kb"
mkdir -p "$KB/sub"
cat > "$KB/index.md" <<'EOF'
# Index
* [Good](good.md) — fine.
EOF
cat > "$KB/good.md" <<'EOF'
---
type: reference
title: Good
---
Body.
EOF
}
teardown() { rm -rf "$(dirname "$KB")"; }
@test "conformant bundle passes" {
run bash "$LINT" "$KB"
[ "$status" -eq 0 ]
}
@test "missing frontmatter is reported" {
printf 'no frontmatter here\n' > "$KB/bad.md"
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"bad.md: missing frontmatter"* ]]
}
@test "frontmatter without type is reported" {
printf -- '---\ntitle: x\n---\nbody\n' > "$KB/notype.md"
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"notype.md"*"type"* ]]
}
@test "unclosed frontmatter is reported, not silently passed" {
# regression: a `---` in the body (fenced code, rule) must not be
# accepted as the closing delimiter of the frontmatter block
cat > "$KB/unclosed.md" <<'EOF'
---
type: reference
title: Unclosed
# Heading after a forgotten closing fence
```markdown
---
name: example
---
```
EOF
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"unclosed.md"* ]]
}
@test "frontmatter in index.md is reported" {
printf -- '---\ntype: x\n---\n# I\n' > "$KB/sub/index.md"
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"index.md must not have frontmatter"* ]]
}
@test "broken relative link is reported" {
printf -- '---\ntype: reference\n---\nsee [x](gone.md)\n' > "$KB/links.md"
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"links.md: broken relative link"* ]]
}
@test "broken wikilink is reported" {
printf -- '---\ntype: reference\n---\nsee [[nowhere]]\n' > "$KB/wiki.md"
run bash "$LINT" "$KB"
[ "$status" -ne 0 ]
[[ "$output" == *"wiki.md: broken wikilink"* ]]
}
@test "missing kb directory exits 2" {
run bash "$LINT" "$KB/no-such-dir"
[ "$status" -eq 2 ]
}