Pi Packages & Themes

Lesson 6: Pi Packages & Themes

Pi packages are the distribution layer: they bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. This is how the community-built surfaces from the last three lessons travel between machines and teams — and the pi.dev gallery is where you browse them.

Installing and managing

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo
pi install /absolute/path/to/package

A package declares its resources either in package.json under the pi key, or via conventional directories (extensions/, skills/, prompts/, themes/). Runtime dependencies must live in dependencies — installation uses production installs (npm install --omit=dev) by default.

Keeping the surface lean

Packages support filtering (choose which resources to pull), enable/disable per resource, and scope and deduplication (the same resource isn't loaded twice when multiple packages provide it). These aren't just organizational niceties — every loaded extension adds tools, commands, and event handlers to the session, and every loaded skill adds its description to the model's view.

Security: Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to run executables. Review the source of third-party packages before installing.

Themes

Themes customize the TUI's colors and styling. The theme setting in settings.json picks one ("dark", "light", or a custom theme), and custom themes can be bundled into packages alongside everything else. It's the least "token-relevant" surface — but a readable TUI keeps your own eye on the footer's cost meter.

🪙 Token angle: Treat every installed package as a standing token tax. Each enabled extension contributes tools and hooks to the session; each enabled skill contributes its description to what the model sees. Enable only what you use, disable the rest, and pin versions for deterministic behavior. A lean tool surface means a smaller system prompt and fewer opportunities for the model to wander into expensive tool calls.

Further Reading

🧠 Knowledge Check

1. What can a pi package bundle?

2. How do you install a package from npm?

3. Why does every installed skill cost tokens even before you use it?