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,48 @@
+---
+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
@@ -0,0 +1,62 @@
+---
+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
@@ -0,0 +1,18 @@
+# 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-... |
+
@@ -0,0 +1,81 @@
+---
+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
@@ -0,0 +1,79 @@
+---
+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
@@ -0,0 +1,35 @@
+---
+type: reference
+title: Skill Commands
+description: The /skill:name command system for explicitly loading and executing skills with optional arguments.
+tags:
+  - unverified
+  - skills
+  - commands
+timestamp: 2026-07-18
+verified: 2026-08-28
+---
+
+# Skill Commands (`/skill:name`)
+
+Skills register as `/skill:name` commands:
+
+```bash
+/skill:brave-search           # Load and execute the skill
+/skill:pdf-tools extract      # Load skill with arguments
+```
+
+Arguments after the command are appended to the skill content as `User: <args>`.
+
+Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
+
+```json
+{
+  "enableSkillCommands": true
+}
+```
+
+## Related
+
+* [Skill Loading](../npx-skills/skill-loading.md) — How skills are normally loaded
+* [Npx Skills Overview](../npx-skills/index.md) — Settings and package control
@@ -0,0 +1,65 @@
+---
+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
@@ -0,0 +1,42 @@
+---
+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
@@ -0,0 +1,70 @@
+---
+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
@@ -0,0 +1,50 @@
+---
+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