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