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