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,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