Extending Pi

Help the user decide what to build and where to find guidance.

What to build

| Goal | Build a… | Where | |------|----------|-------| | Teach Pi a workflow or how to use a tool/API/CLI | Skill | Read skill-creator/SKILL.md for detailed guidance | | Give Pi a new tool, command, or runtime behavior | Extension | Read Pi docs: docs/extensions.md | | Reuse a prompt pattern with variables | Prompt template | Read Pi docs: docs/prompt-templates.md | | Set project-wide coding guidelines | Context file | AGENTS.md in project root or .pi/agent/ — just markdown | | Change Pi's appearance | Theme | Read Pi docs: docs/themes.md | | Add a model or provider | Custom model | Read Pi docs: docs/models.md (JSON) or docs/custom-provider.md (extension) | | Share any of the above | Package | 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_query tool" → Extension (registerTool)