pi-package-creator

# Pi Package Creator ## Overview Use this skill to design and ship Pi packages with a narrow public promise and a real install/validation loop. Focus on package surface, installability, and dogfooding, not just folder scaffolding. Read: - `references/surface-design.md` before deciding what the package should ship - `references/validation.md` before calling the package done For advanced surface-specific details, inspect the installed Pi docs only after you have a resolved local docs path. Use the same `pi` binary you will validate with when checking `pi --help` for CLI flags. Do not guess where Pi's installed package tree lives on disk. If `skill-creator` is available and the package includes multiple skills or a skill with bundled resources beyond a single `SKILL.md`, use it for the internal skill design. Otherwise keep the work inside this skill and focus on package boundary, manifest, install flow, README, and proof. ## Workflow ### 1. Lock the package promise Start by answering: - What is the package for in one sentence? - What should a user be able to install and use immediately? - Which Pi resources does that require: `extensions`, `skills`, `prompts`, or `themes`? - What should explicitly stay out of scope for `v1`? Prefer one narrow package promise over a kitchen-sink bundle. ### 2. Choose the smallest package surface Pick only the resource types that the package actually needs: - `extensions` for commands, hooks, tools, ambient behavior, UI, or plumbing - `skills` for reusable workflows and domain instructions - `prompts` for reusable prompt templates - `themes` for visual presentation only Do not add a second surface without a real user-facing reason. ### 3. Build the package shape Create or tighten: - `package.json` - only the resource directories that are actually used - a README that explains what the package is, how to install it, how to prove it works, and what its limits are For `package.json`: - include `name`, `version`, `license` - include `keywords` with `pi-package` - use the exact `pi` manifest keys Pi supports: `extensions`, `skills`, `prompts`, `themes` - point manifest entries at relative paths - ship only needed files Keep public metadata honest: - if the package is Pi-only, say so - if install is local-path-only today, say so - do not point homepage/repository/bugs at URLs that are not ready ### 4. Validate with the package manager, not just direct paths The release gate is not "the files look right." The gate is "Pi can install and use this package." Always validate in this order: 1. repo-local tests/build checks 2. install into a temporary Pi agent dir 3. confirm the package is listed 4. smoke the actual public surface 5. dogfood in a real repo only after the temp install works Use the validation flow in `references/validation.md`. Do not rely only on `--extension`, `--skill`, or ad hoc file loading. Those are fine for inner-loop debugging of one component, but the package promise is still `pi install`. - Keep package docs and package behavior in sync. - Use scratch repos or temp agent dirs before touching real agent state. - If the package mutates repo files, prove it in a scratch repo first. - If the package is still private or unpublished, avoid public-install copy that implies otherwise.