How do I install the Pi Package Development skill?

Run npx skillmds@latest add ryan-brosas/pi-package-development in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Pi Package Development safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Pi Package Development?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Pi Package Development free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Pi Package Development?

ryan-brosas (@ryan-brosas) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Pi Package Development by ryan-brosas

Name: Pi Package Development
Author: ryan-brosas

Pi Package Development

Use when creating, editing, structuring, testing, or shipping a pi package or pi extension (package.json pi manifest, pi-package keyword, peerDependencies, bundling, pi install -e testing, gallery metadata) — encodes the packages.md contract. Trigger-first; pick over generic npm-package advice.

ryan-brosas db86c02 3.4 KB Updated Sep 17, 2026

File contents

Developing pi Packages

Core Principle

A pi package is an npm/git package with a pi manifest declaring resources. The contract lives in the local docs — re-read it before structural changes; this skill is the checklist, not the spec.

When to Use / NOT

Use when: creating or modifying a pi package (extensions, skills, prompts, themes); wiring package.json for pi; testing with pi -e / pi install; publishing.
NOT when: building non-package npm libraries; pi CLI core development (repo, not package).

Workflow

Re-read the spec: open the local docs file (References) — it is authoritative and versioned with the installed pi.
Manifest: add a pi key to package.json — "extensions", "skills", "prompts", "themes" arrays, relative to package root, globs and !exclusions allowed. No manifest? Conventional dirs (extensions/, skills/, prompts/, themes/) are auto-discovered.
Discoverability: include "pi-package" in keywords (gallery: pi.dev/packages). Optional pi.video (MP4) / pi.image (PNG/JPEG/GIF/WebP) preview fields; video wins if both.
Dependencies rule (the common mistake):
- Third-party runtime deps → dependencies (pi runs npm install on package install).
- Core pi packages — @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox — import freely but list in peerDependencies with "*" and never bundle them.
- Other pi packages → dependencies + bundledDependencies, reference via node_modules/<pkg>/... paths.
Dev loop: pi -e /abs/path/to/pkg loads a one-off without installing; pi install <source> persists (user vs -l project settings); pi config toggles resources; pi list shows installs.
Stop condition: manifest valid, keyword set, dependency tiers correct, package loads via pi -e.

Red Flags

HARD-GATE: never put core pi packages (pi-ai, pi-agent-core, pi-coding-agent, pi-tui, typebox) in dependencies or bundle them — peerDependencies with "*" only.
Do not ship resources outside files/the tarball — an extension importing a file npm did not pack breaks on install.
Dot-prefixed resources are not glob-discovered; list them directly in the manifest.
Pinning a git source ref is intentional (pi update never moves it); use pi install git:host/user/repo@new-ref to move it.
Settings filters (object form) only narrow what the manifest allows — they cannot add resources.

Verification

bun -e script asserting: pi manifest present, pi-package keyword, entry files exist, core packages in peerDependencies with "*" and absent from dependencies, files complete.
Load the package: pi -e <path> and exercise the extension in a session.

References

~/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/packages.md — the spec (mirrors https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md).
~/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md — extension API surface.

---name: pi-package-developmentdescription: Use when creating, editing, structuring, testing, or shipping a pi package or pi extension (package.json pi manifest, pi-package keyword, peerDependencies, bundling, pi install -e testing, gallery metadata) — encodes the packages.md contract. Trigger-first; pick over generic npm-package advice.---# Developing pi Packages## Core PrincipleA pi package is an npm/git package with a `pi` manifest declaring resources. The contract lives in the local docs — re-read it before structural changes; this skill is the checklist, not the spec.## When to Use / NOT- **Use when:** creating or modifying a pi package (extensions, skills, prompts, themes); wiring `package.json` for pi; testing with `pi -e` / `pi install`; publishing.- **NOT when:** building non-package npm libraries; pi CLI core development (repo, not package).## Workflow1. **Re-read the spec:** open the local docs file (References) — it is authoritative and versioned with the installed pi.2. **Manifest:** add a `pi` key to `package.json` — `"extensions"`, `"skills"`, `"prompts"`, `"themes"` arrays, relative to package root, globs and `!exclusions` allowed. No manifest? Conventional dirs (`extensions/`, `skills/`, `prompts/`, `themes/`) are auto-discovered.3. **Discoverability:** include `"pi-package"` in `keywords` (gallery: pi.dev/packages). Optional `pi.video` (MP4) / `pi.image` (PNG/JPEG/GIF/WebP) preview fields; video wins if both.4. **Dependencies rule (the common mistake):** - Third-party runtime deps → `dependencies` (pi runs `npm install` on package install). - Core pi packages — `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox` — import freely but list in `peerDependencies` with `"*"` and never bundle them. - Other pi packages → `dependencies` + `bundledDependencies`, reference via `node_modules/<pkg>/...` paths.5. **Dev loop:** `pi -e /abs/path/to/pkg` loads a one-off without installing; `pi install <source>` persists (user vs `-l` project settings); `pi config` toggles resources; `pi list` shows installs.6. **Stop condition:** manifest valid, keyword set, dependency tiers correct, package loads via `pi -e`.## Red Flags- **HARD-GATE:** never put core pi packages (`pi-ai`, `pi-agent-core`, `pi-coding-agent`, `pi-tui`, `typebox`) in `dependencies` or bundle them — `peerDependencies` with `"*"` only.- Do not ship resources outside `files`/the tarball — an extension importing a file npm did not pack breaks on install.- Dot-prefixed resources are not glob-discovered; list them directly in the manifest.- Pinning a git source ref is intentional (`pi update` never moves it); use `pi install git:host/user/repo@new-ref` to move it.- Settings filters (object form) only narrow what the manifest allows — they cannot add resources.## Verification- `bun -e` script asserting: `pi` manifest present, `pi-package` keyword, entry files exist, core packages in `peerDependencies` with `"*"` and absent from `dependencies`, `files` complete.- Load the package: `pi -e <path>` and exercise the extension in a session.## References- `~/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/packages.md` — the spec (mirrors https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md).- `~/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md` — extension API surface.

Frequently asked questions