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

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
2026-10-19 02:58:52 -07:00
parent e86e60af39
commit 651924a4bc
41 changed files with 439 additions and 1686 deletions
@@ -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"
@@ -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`.

@@ -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)
@@ -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
@@ -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

@@ -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)
@@ -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).
@@ -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.
@@ -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.
@@ -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)
@@ -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.
@@ -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)
@@ -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).
@@ -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.
@@ -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)
@@ -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
@@ -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.
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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-... |
-
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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`
@@ -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... |
-
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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