From 651924a4bcd4e315f8ba18c66c8b163697e61833 Mon Sep 17 00:00:00 2001 From: Frank Date: Mon, 19 Oct 2026 02:58:52 -0700 Subject: [PATCH] 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 --- omp-docs/core/index-doc.md | 75 -------- omp-docs/core/index.md | 1 - omp-docs/engineering/agents-files.md | 2 +- omp-docs/engineering/index.md | 2 +- omp-docs/engineering/plugins.md | 2 +- omp-docs/engineering/skills-ecosystem.md | 144 --------------- omp-docs/packages/index.md | 2 +- omp-docs/packages/pi-browser-use.md | 2 +- omp-docs/packages/pi-permission-system.md | 2 +- omp-docs/pi/skills.md | 2 +- omp-docs/skills/agent-skills.md | 105 +++++++++++ omp-docs/skills/ecosystem.md | 77 ++++++++ omp-docs/skills/index.md | 13 +- omp-docs/skills/npx-skills.md | 164 ----------------- omp-docs/skills/skills-cli.md | 127 ++++++++++++++ .../store-wiring.md} | 5 +- omp-docs/skills/vercel-skills.md | 166 ------------------ omp-docs/tools/index.md | 23 +-- omp-docs/tools/niri/screenshots.md | 2 +- omp-docs/tools/npx-skills/best-practices.md | 48 ----- omp-docs/tools/npx-skills/ecosystem.md | 62 ------- omp-docs/tools/npx-skills/index.md | 18 -- omp-docs/tools/npx-skills/installation.md | 81 --------- .../tools/npx-skills/package-structure.md | 79 --------- omp-docs/tools/npx-skills/skill-commands.md | 35 ---- .../tools/npx-skills/skill-file-structure.md | 65 ------- omp-docs/tools/npx-skills/skill-loading.md | 42 ----- omp-docs/tools/npx-skills/skills-spec.md | 70 -------- .../tools/npx-skills/skills-vs-extensions.md | 50 ------ .../tools/vercel-labs-skills/agent-support.md | 84 --------- omp-docs/tools/vercel-labs-skills/commands.md | 116 ------------ .../tools/vercel-labs-skills/env-variables.md | 33 ---- omp-docs/tools/vercel-labs-skills/index.md | 19 -- .../vercel-labs-skills/installation-scope.md | 36 ---- .../tools/vercel-labs-skills/lock-file.md | 43 ----- .../tools/vercel-labs-skills/related-links.md | 43 ----- .../vercel-labs-skills/skill-discovery.md | 63 ------- .../tools/vercel-labs-skills/skill-format.md | 70 -------- .../vercel-labs-skills/source-formats.md | 43 ----- scripts/kb-lint.sh | 17 +- tests/kb-lint.bats | 92 ++++++++++ 41 files changed, 439 insertions(+), 1686 deletions(-) delete mode 100644 omp-docs/core/index-doc.md delete mode 100644 omp-docs/engineering/skills-ecosystem.md create mode 100644 omp-docs/skills/agent-skills.md create mode 100644 omp-docs/skills/ecosystem.md delete mode 100644 omp-docs/skills/npx-skills.md create mode 100644 omp-docs/skills/skills-cli.md rename omp-docs/{tools/vercel-labs-skills/skill-store-wiring.md => skills/store-wiring.md} (90%) delete mode 100644 omp-docs/skills/vercel-skills.md delete mode 100644 omp-docs/tools/npx-skills/best-practices.md delete mode 100644 omp-docs/tools/npx-skills/ecosystem.md delete mode 100644 omp-docs/tools/npx-skills/index.md delete mode 100644 omp-docs/tools/npx-skills/installation.md delete mode 100644 omp-docs/tools/npx-skills/package-structure.md delete mode 100644 omp-docs/tools/npx-skills/skill-commands.md delete mode 100644 omp-docs/tools/npx-skills/skill-file-structure.md delete mode 100644 omp-docs/tools/npx-skills/skill-loading.md delete mode 100644 omp-docs/tools/npx-skills/skills-spec.md delete mode 100644 omp-docs/tools/npx-skills/skills-vs-extensions.md delete mode 100644 omp-docs/tools/vercel-labs-skills/agent-support.md delete mode 100644 omp-docs/tools/vercel-labs-skills/commands.md delete mode 100644 omp-docs/tools/vercel-labs-skills/env-variables.md delete mode 100644 omp-docs/tools/vercel-labs-skills/index.md delete mode 100644 omp-docs/tools/vercel-labs-skills/installation-scope.md delete mode 100644 omp-docs/tools/vercel-labs-skills/lock-file.md delete mode 100644 omp-docs/tools/vercel-labs-skills/related-links.md delete mode 100644 omp-docs/tools/vercel-labs-skills/skill-discovery.md delete mode 100644 omp-docs/tools/vercel-labs-skills/skill-format.md delete mode 100644 omp-docs/tools/vercel-labs-skills/source-formats.md create mode 100755 tests/kb-lint.bats diff --git a/omp-docs/core/index-doc.md b/omp-docs/core/index-doc.md deleted file mode 100644 index 5abc3e7..0000000 --- a/omp-docs/core/index-doc.md +++ /dev/null @@ -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//index.md` (multi-file) or `tools/.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" diff --git a/omp-docs/core/index.md b/omp-docs/core/index.md index 5ab5d59..608948a 100644 --- a/omp-docs/core/index.md +++ b/omp-docs/core/index.md @@ -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`. diff --git a/omp-docs/engineering/agents-files.md b/omp-docs/engineering/agents-files.md index 8858132..e74e10e 100644 --- a/omp-docs/engineering/agents-files.md +++ b/omp-docs/engineering/agents-files.md @@ -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) diff --git a/omp-docs/engineering/index.md b/omp-docs/engineering/index.md index f8cc1a2..be2c20a 100644 --- a/omp-docs/engineering/index.md +++ b/omp-docs/engineering/index.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 diff --git a/omp-docs/engineering/plugins.md b/omp-docs/engineering/plugins.md index e80716e..f75d319 100644 --- a/omp-docs/engineering/plugins.md +++ b/omp-docs/engineering/plugins.md @@ -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 diff --git a/omp-docs/engineering/skills-ecosystem.md b/omp-docs/engineering/skills-ecosystem.md deleted file mode 100644 index 1818b00..0000000 --- a/omp-docs/engineering/skills-ecosystem.md +++ /dev/null @@ -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 # 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) diff --git a/omp-docs/packages/index.md b/omp-docs/packages/index.md index d247e82..17cc244 100644 --- a/omp-docs/packages/index.md +++ b/omp-docs/packages/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:` 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). diff --git a/omp-docs/packages/pi-browser-use.md b/omp-docs/packages/pi-browser-use.md index 09fe29a..9a3fcbf 100644 --- a/omp-docs/packages/pi-browser-use.md +++ b/omp-docs/packages/pi-browser-use.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. diff --git a/omp-docs/packages/pi-permission-system.md b/omp-docs/packages/pi-permission-system.md index 2be3c11..4702499 100644 --- a/omp-docs/packages/pi-permission-system.md +++ b/omp-docs/packages/pi-permission-system.md @@ -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. diff --git a/omp-docs/pi/skills.md b/omp-docs/pi/skills.md index e5631d0..ff57516 100644 --- a/omp-docs/pi/skills.md +++ b/omp-docs/pi/skills.md @@ -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) diff --git a/omp-docs/skills/agent-skills.md b/omp-docs/skills/agent-skills.md new file mode 100644 index 0000000..c3f90be --- /dev/null +++ b/omp-docs/skills/agent-skills.md @@ -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. diff --git a/omp-docs/skills/ecosystem.md b/omp-docs/skills/ecosystem.md new file mode 100644 index 0000000..c785e51 --- /dev/null +++ b/omp-docs/skills/ecosystem.md @@ -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) diff --git a/omp-docs/skills/index.md b/omp-docs/skills/index.md index b7da9a3..8424b51 100644 --- a/omp-docs/skills/index.md +++ b/omp-docs/skills/index.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). diff --git a/omp-docs/skills/npx-skills.md b/omp-docs/skills/npx-skills.md deleted file mode 100644 index a351bc4..0000000 --- a/omp-docs/skills/npx-skills.md +++ /dev/null @@ -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. diff --git a/omp-docs/skills/skills-cli.md b/omp-docs/skills/skills-cli.md new file mode 100644 index 0000000..bbdc737 --- /dev/null +++ b/omp-docs/skills/skills-cli.md @@ -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 ` | `a` | Install skills from a source. | +| `skills use [@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 ` filter). | +| `skills find [query]` | | Interactive (fzf-style) or keyword search; `--owner ` 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 ` | Target specific agents (`'*'` for all). | +| `-s, --skill ` | 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/`), 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 | `.//skills/` | +| Global | `-g` | `~//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//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) diff --git a/omp-docs/tools/vercel-labs-skills/skill-store-wiring.md b/omp-docs/skills/store-wiring.md similarity index 90% rename from omp-docs/tools/vercel-labs-skills/skill-store-wiring.md rename to omp-docs/skills/store-wiring.md index c245815..8508701 100644 --- a/omp-docs/tools/vercel-labs-skills/skill-store-wiring.md +++ b/omp-docs/skills/store-wiring.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 diff --git a/omp-docs/skills/vercel-skills.md b/omp-docs/skills/vercel-skills.md deleted file mode 100644 index 11c8f84..0000000 --- a/omp-docs/skills/vercel-skills.md +++ /dev/null @@ -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 [options] -``` - -| Option | Description | -|--------|-------------| -| `-g, --global` | Install to user directory (`~/`) | -| `-a, --agent ` | Target specific agents | -| `-s, --skill ` | 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 [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)_ | `.//skills/` | Committed with project | -| **Global** | `-g` | `~//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. diff --git a/omp-docs/tools/index.md b/omp-docs/tools/index.md index d6314c8..6376ee4 100644 --- a/omp-docs/tools/index.md +++ b/omp-docs/tools/index.md @@ -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. diff --git a/omp-docs/tools/niri/screenshots.md b/omp-docs/tools/niri/screenshots.md index b6a446e..a148834 100644 --- a/omp-docs/tools/niri/screenshots.md +++ b/omp-docs/tools/niri/screenshots.md @@ -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 diff --git a/omp-docs/tools/npx-skills/best-practices.md b/omp-docs/tools/npx-skills/best-practices.md deleted file mode 100644 index 1d87dc4..0000000 --- a/omp-docs/tools/npx-skills/best-practices.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/ecosystem.md b/omp-docs/tools/npx-skills/ecosystem.md deleted file mode 100644 index 6d34463..0000000 --- a/omp-docs/tools/npx-skills/ecosystem.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/index.md b/omp-docs/tools/npx-skills/index.md deleted file mode 100644 index 1808b41..0000000 --- a/omp-docs/tools/npx-skills/index.md +++ /dev/null @@ -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-... | - diff --git a/omp-docs/tools/npx-skills/installation.md b/omp-docs/tools/npx-skills/installation.md deleted file mode 100644 index 022ed02..0000000 --- a/omp-docs/tools/npx-skills/installation.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/package-structure.md b/omp-docs/tools/npx-skills/package-structure.md deleted file mode 100644 index f7b29ab..0000000 --- a/omp-docs/tools/npx-skills/package-structure.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/skill-commands.md b/omp-docs/tools/npx-skills/skill-commands.md deleted file mode 100644 index 35d7a8a..0000000 --- a/omp-docs/tools/npx-skills/skill-commands.md +++ /dev/null @@ -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: `. - -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 diff --git a/omp-docs/tools/npx-skills/skill-file-structure.md b/omp-docs/tools/npx-skills/skill-file-structure.md deleted file mode 100644 index 199ffa2..0000000 --- a/omp-docs/tools/npx-skills/skill-file-structure.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/skill-loading.md b/omp-docs/tools/npx-skills/skill-loading.md deleted file mode 100644 index 8635fef..0000000 --- a/omp-docs/tools/npx-skills/skill-loading.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/skills-spec.md b/omp-docs/tools/npx-skills/skills-spec.md deleted file mode 100644 index 342a42c..0000000 --- a/omp-docs/tools/npx-skills/skills-spec.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/npx-skills/skills-vs-extensions.md b/omp-docs/tools/npx-skills/skills-vs-extensions.md deleted file mode 100644 index 852ca95..0000000 --- a/omp-docs/tools/npx-skills/skills-vs-extensions.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/vercel-labs-skills/agent-support.md b/omp-docs/tools/vercel-labs-skills/agent-support.md deleted file mode 100644 index 23265ee..0000000 --- a/omp-docs/tools/vercel-labs-skills/agent-support.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/vercel-labs-skills/commands.md b/omp-docs/tools/vercel-labs-skills/commands.md deleted file mode 100644 index 42c154e..0000000 --- a/omp-docs/tools/vercel-labs-skills/commands.md +++ /dev/null @@ -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 [options] -``` - -### Options - -| Option | Description | -|--------|-------------| -| `-g, --global` | Install to user directory (`~/`) instead of project (`./`) | -| `-a, --agent ` | Target specific agents | -| `-s, --skill ` | 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 [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 diff --git a/omp-docs/tools/vercel-labs-skills/env-variables.md b/omp-docs/tools/vercel-labs-skills/env-variables.md deleted file mode 100644 index 9a0b5d9..0000000 --- a/omp-docs/tools/vercel-labs-skills/env-variables.md +++ /dev/null @@ -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` diff --git a/omp-docs/tools/vercel-labs-skills/index.md b/omp-docs/tools/vercel-labs-skills/index.md deleted file mode 100644 index f67a19e..0000000 --- a/omp-docs/tools/vercel-labs-skills/index.md +++ /dev/null @@ -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... | - diff --git a/omp-docs/tools/vercel-labs-skills/installation-scope.md b/omp-docs/tools/vercel-labs-skills/installation-scope.md deleted file mode 100644 index 822b5ec..0000000 --- a/omp-docs/tools/vercel-labs-skills/installation-scope.md +++ /dev/null @@ -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)_ | `.//skills/` | Committed with your project, shared with team | -| **Global** | `-g` | `~//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 diff --git a/omp-docs/tools/vercel-labs-skills/lock-file.md b/omp-docs/tools/vercel-labs-skills/lock-file.md deleted file mode 100644 index f80c6cc..0000000 --- a/omp-docs/tools/vercel-labs-skills/lock-file.md +++ /dev/null @@ -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/?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 diff --git a/omp-docs/tools/vercel-labs-skills/related-links.md b/omp-docs/tools/vercel-labs-skills/related-links.md deleted file mode 100644 index 1ef2a34..0000000 --- a/omp-docs/tools/vercel-labs-skills/related-links.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/vercel-labs-skills/skill-discovery.md b/omp-docs/tools/vercel-labs-skills/skill-discovery.md deleted file mode 100644 index fb4b3c8..0000000 --- a/omp-docs/tools/vercel-labs-skills/skill-discovery.md +++ /dev/null @@ -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//SKILL.md` -- **One extra level deep** for catalog layouts: `skills///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 diff --git a/omp-docs/tools/vercel-labs-skills/skill-format.md b/omp-docs/tools/vercel-labs-skills/skill-format.md deleted file mode 100644 index c04b896..0000000 --- a/omp-docs/tools/vercel-labs-skills/skill-format.md +++ /dev/null @@ -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 diff --git a/omp-docs/tools/vercel-labs-skills/source-formats.md b/omp-docs/tools/vercel-labs-skills/source-formats.md deleted file mode 100644 index 18e320d..0000000 --- a/omp-docs/tools/vercel-labs-skills/source-formats.md +++ /dev/null @@ -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 diff --git a/scripts/kb-lint.sh b/scripts/kb-lint.sh index 9fe0e85..aa27243 100755 --- a/scripts/kb-lint.sh +++ b/scripts/kb-lint.sh @@ -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. diff --git a/tests/kb-lint.bats b/tests/kb-lint.bats new file mode 100755 index 0000000..79fead1 --- /dev/null +++ b/tests/kb-lint.bats @@ -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 ] +}