Extending Pi
Help the user decide what to build, scaffold the right files, and point to detailed guidance.
What to build
| Goal | Build a… | Key files to create | Where |
|---|---|---|---|
| Teach Pi a workflow or how to use a tool/API/CLI | Skill | SKILL.md with YAML frontmatter + markdown body |
Read skill-creator/SKILL.md for detailed guidance |
| Give Pi a new tool, command, or runtime behavior | Extension | manifest.json + src/index.ts entry point |
Read Pi docs: docs/extensions.md |
| Reuse a prompt pattern with variables | Prompt template | .md file with {{variable}} placeholders |
Read Pi docs: docs/prompt-templates.md |
| Set project-wide coding guidelines | Context file | AGENTS.md in project root or .pi/agent/ — just markdown |
No extra docs needed |
| Change Pi's appearance | Theme | theme.json with color and font definitions |
Read Pi docs: docs/themes.md |
| Add a model or provider | Custom model | models.json or extension with provider registration |
Read Pi docs: docs/models.md (JSON) or docs/custom-provider.md (extension) |
| Share any of the above | Package | manifest.json with dependencies and entry points |
Read Pi docs: docs/packages.md |
Skill vs Extension — the fuzzy boundary
If bash + instructions can do it, prefer a Skill (simpler, no code to maintain). If you need event hooks, typed tools, UI components, or policy enforcement, use an Extension.
Examples:
- "Pi should know our deploy process" → Skill (workflow instructions)
- "Pi should confirm before
rm -rf" → Extension (event interception) - "Pi should use Brave Search" → Skill (instructions + CLI scripts)
- "Pi should have a structured
db_querytool" → Extension (registerTool)
Minimal working examples
Skill — place in .pi/skills/my-skill/SKILL.md:
---
name: my-skill
description: Does X when the user asks to Y.
---
# My Skill
Step 1: ...
Step 2: ...
Extension — create manifest.json + src/index.ts:
{ "name": "my-extension", "version": "0.1.0", "entry": "src/index.ts" }
import { registerTool } from "@anthropic/pi-sdk";
registerTool("my_tool", { description: "..." }, async (input) => { /* ... */ });
Quick-start steps
- Pick the artifact type from the table above.
- Scaffold the files — create the key files using the minimal examples above.
- Validate locally:
- Skills: place
SKILL.mdin.pi/skills/<name>/and invoke the skill — if it doesn't trigger, check thatnameanddescriptionin frontmatter are set correctly. - Extensions: run
pi ext install .— if it fails with "missing entry", verify theentrypath inmanifest.jsonpoints to an existing file.
- Skills: place
- Package and share — follow
docs/packages.mdto bundle and publish.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.