command-center/omp-docs/skills/npx-skills.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
reference	Npx Skills — Distribution and Installation Patterns	Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system.	skills npm agent-skills distribution pi-package unverified	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, 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)

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

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)

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

{
  "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 for the meta-installer tool.
• The Agent Skills specification is the canonical format.