docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,164 @@
+---
+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.