extension-creator

Scaffold, implement, and validate Pi TypeScript extensions for tools, commands, and lifecycle hooks.

2|Updated Aug 17, 2026
One-click install
npx skills add https://github.com/yyy0107/pi-workbench --skill extension-creator-yyy0107
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: extension-creator
Source: https://github.com/yyy0107/pi-workbench/tree/main/packages/agent-runtime/runtimes/pi/server/src/internal-skills/extension-creator
Command: npx skills add https://github.com/yyy0107/pi-workbench --skill extension-creator-yyy0107

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Building a Pi extension from scratch requires knowing the ExtensionAPI factory contract, discovery rules, output truncation limits, and validation steps. This Skill guides the full workflow so the generated extension actually loads and behaves correctly instead of stopping at a boilerplate scaffold. ## Core Features & Use Cases - Guided Scaffolding: Generate command, tool, or event extension starters with normalized names, correct destinations (project, user, or package scope), and optional Pi package manifests via Python scripts. - Reference-Driven Implementation: Map each task (tools, hooks, providers, terminal UI) to the matching pi-docs reference and verify signatures against the installed SDK. - Bounded Output & Validation: Enforce byte/line truncation budgets on tool results and validate structure or load the extension with the recorded Node/SDK runtime. - Use Case: Ask to add a custom tool that queries an internal API; the Skill scaffolds the extension, implements typed parameters with truncated output, runs the load check, and explains how to reload the session to pick it up. ## Quick Start Create a Pi extension named text-helper that registers a custom tool and validate that it loads correctly.

Frequently Asked Questions about extension-creator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Pi extension with a custom tool?▼

Run the create_extension.py script with --kind tool to scaffold a typed echo tool, then implement your logic in the generated index.ts using pi.registerTool with a typebox schema. Validate it with validate_extension.py --load to confirm the SDK loads the factory and registers the tool.

How do I scaffold a distributable Pi package?▼

Use create_extension.py with --package and --path to generate a package.json containing pi.extensions, pi-package keywords, and peer dependencies. The package starts as private and lives outside automatic discovery, so install it through the Pi package flow when ready.

Where are Pi extensions discovered automatically?▼

Project extensions live in .pi/extensions under the current working directory and require project trust. User-scope extensions go in the userResourceDir from the skill's runtime.json, falling back to $PI_CODING_AGENT_DIR or ~/.pi/agent.

Does the extension load check verify tool behavior?▼

No. The --load check only executes the factory in a subprocess and reports registered tools, commands, and events. It does not dispatch events, invoke tools, typecheck the extension, or act as a security sandbox, so run separate behavior tests.

Why must Pi tool output be truncated?▼

Neither tool registration nor compaction automatically bounds custom output, so oversized results can flood the context. Reuse Pi's truncateHead/truncateTail with the 50 KiB and 2,000 line defaults, and spill overflow to a readable file with offset guidance.

When should I use a skill or prompt instead of a Pi extension?▼

Use a Pi extension for executable tools, commands, event hooks, providers, and terminal rendering. For reusable instructions use skill-creator, and for a reusable text command consider a Pi prompt template instead of writing TypeScript.