Frank
02883d3ed2
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.
165 lines
5.0 KiB
Markdown
165 lines
5.0 KiB
Markdown
---
|
|
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.
|