Publishing packages

Bundle extensions, themes, skills and prompts; ship via npm or git; get discovered.

What a pi package is

Any npm package or git repo can be a pi package. It bundles any mix of extensions, skills, prompt templates and themes, and users install it with one command:

pi install npm:@you/your-package     # from npm (pin with @1.2.3)
pi install git:github.com/you/repo   # from git (pin with @v1 / @sha)
pi install ./local/path              # from disk, for development

npm installs land in ~/.pi/agent/npm/, git installs in ~/.pi/agent/git/<host>/<path> (or under the project’s .pi/ when installed with -l). Dependencies in your package.json are installed automatically. Users manage everything with pi list, pi update, pi remove.

Layout: convention or manifest

Easiest: use the conventional directories and ship with zero config —

your-package/
├── package.json
├── extensions/   # *.ts / *.js auto-discovered
├── skills/       # folders containing SKILL.md
├── prompts/      # *.md prompt templates
└── themes/       # *.json themes

Need control? Declare resources explicitly under the pi key (globs and !exclusions supported):

{
  "name": "@you/your-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

The discovery checklist

Add "pi-package" to keywords — that’s how the official pi.dev package search indexes npm packages.
Write a real description — one sentence, said plainly. It’s your listing everywhere.
README with a demo — what it does, a screenshot or cast, configuration, and any API keys it needs.
LICENSE file — people can’t legally use unlicensed code.
Publish: npm publish (or just push the git repo — git-only packages work fine and install straight from the URL).
Submit it to piext — one small PR adds you to this curated directory, including theme previews if you ship themes.

npm or git?

	npm	git
Versioning	semver, lockstep with `pi update`	tags/branches/SHAs
Discovery	pi.dev keyword search + piext	piext + word of mouth
Friction	needs an npm account	none — push and share
Best for	polished, maintained packages	personal setups, experiments, big monorepos

Plenty of great packages are git-only (pi-autoresearch, tmustier/pi-extensions) — don’t let npm ceremony stop you from sharing.

Be a good citizen

Users grant your code full system access the moment they install. Earn it: no obfuscated code, no phoning home without documentation, declare required credentials up front, and keep your tool output truncated so you don’t blow up their context window.

📖 This is a community quickstart. The canonical reference is the official pi documentation — always trust it over us if the two disagree.