name: "pi-development"
description: "Develop or review Pi extensions, themes, packages, SDK integrations, and core behavior."
createdAt: "2026-09-11T18:46:00.191369+00:00"
repoUrl: "https://skillz.supply/skills/did:plc:xbtmt2zjwlrfegqvch7fboei/skills.pi-development/SKILL.md"
# Pi development Treat Pi as an extension-first system. Decide whether the request belongs in a theme, skill, extension, package, SDK consumer, or Pi core before writing code. ## Orient from current sources Find the installed `@earendil-works/pi-coding-agent` version. Read the documentation and examples relevant to the requested surface, following cross-references when they resolve a specific question. Prefer public APIs over private runtime patches. When upstream source is needed, use the available repository cache or clone https://github.com/earendil-works/pi into a suitable workspace. An installed librarian skill can help; do not assume its path or require it. Compare the checkout revision with the installed version before relying on an API. Follow the target project's TypeScript conventions and tooling. Start with these docs as applicable: - `README.md` - `docs/extensions.md` - `docs/tui.md` - `docs/themes.md` - `docs/skills.md` - `docs/packages.md` - `docs/sdk.md` - `docs/custom-provider.md` - `docs/settings.md` ## Survey existing work first Check official examples first. When evaluating existing packages or choosing an extension approach, also inspect relevant community work: - package gallery: `https://pi.dev/packages` - npm keyword search: `https://www.npmjs.com/search?q=keywords%3Api-package` - upstream examples: `packages/coding-agent/examples/extensions/` Reuse cached checkouts where available. Read package manifests, source, tests, compatibility claims, and recent activity—not only README screenshots. Pi packages execute with full user permissions; review source before recommending installation. ## Choose the smallest owning surface - **theme**: color tokens only - **skill**: model workflow and reference material; no runtime UI - **extension**: lifecycle behavior, commands, tools, renderers, headers, editors, widgets, status, footer, or overlays - **package**: distributable bundle of extensions, skills, prompts, or themes - **SDK consumer**: a separate application embedding Pi - **Pi core**: only when the public extension API cannot own the behavior cleanly or the default should improve for everyone State the API gap before proposing a core change. ## Use public provenance contracts Never infer resource ownership from display names when Pi provides metadata. - `pi.getCommands()` returns extension commands, prompts, and skills with canonical `sourceInfo`. - `pi.getAllTools()` returns tool metadata with canonical `sourceInfo`. - Treat `sourceInfo.source`, `scope`, `origin`, `path`, and `baseDir` as the ownership contract. - Preserve distinctions among built-in, user-local, project-local, temporary/CLI, npm, git, and SDK sources. - Parse untrusted configuration or package metadata once at its boundary. If a required resource type is not publicly enumerable, do not reach into private fields silently. Either design around the limitation or propose the narrow public API needed. ## Startup UI specifics Pi's startup header and loaded-resource listing are separate surfaces. - `ctx.ui.setHeader()` replaces only the built-in logo/help header. - `quietStartup` suppresses Pi's built-in header and loaded-resource listing; an extension can still install its own header during `session_start`. - Pi's compact startup listing favors names. Expanding with the configured tool-output key (normally Ctrl+O) shows resources grouped by project/user/path and package source. - Diagnostics and collisions must remain visible even in a compact redesign. - A polished startup should lead with useful state, use restrained semantic color, summarize counts or categories, expose provenance on demand, fit narrow terminals, and avoid requiring Nerd Fonts without an ASCII fallback. Prefer a compact overview plus an interactive or expandable detail view over another permanent wall of text. ## TUI implementation rules - Guard terminal-only behavior with `ctx.mode === "tui"`. - Use the callback-provided theme. - Keep every rendered line within `width`; use ANSI-aware width/truncation helpers. - Rebuild pre-themed cached content from `invalidate()`. - Dispose timers, subscriptions, watchers, and components during `session_shutdown`. - Prefer built-in components such as `Text`, `Container`, `SelectList`, `SettingsList`, `DynamicBorder`, and `BorderedLoader`. - Use `setHeader`, `setWidget`, `setStatus`, `setFooter`, or `setEditorComponent` only for the surface actually owned. - Keep regular and fullscreen modes usable. ## Validate honestly Run the repository's required checks and tests affected by the change. For visual changes, select relevant cases from: - narrow and wide widths - light and dark themes - regular and fullscreen TUI modes - startup, reload, new, resume, and shutdown lifecycle - empty, local-only, package-heavy, and diagnostic/error resource states - terminals with and without Nerd Fonts Use `PI_TUI_WRITE_LOG` or a PTY-based test when ANSI output or cursor behavior matters. Capture a screenshot or deterministic rendered-line fixture for meaningful visual changes. ## Deliver the decision Report: 1. what already exists and how it differs, 2. what the current Pi core already supports, 3. the smallest recommended change, 4. any public API gap, 5. security/compatibility tradeoffs, 6. exact validation performed.