---
name: extending-pi
description: Guide for changing or extending Pi's behaviour. Use when someone wants to modify how Pi behaves, add capabilities, decide which Pi extension point or artifact to use, build or package an extension, create an Agent Skill, add prompt templates/themes/context/model providers, configure Pi resources, or asks whether a Pi internal patch is needed.
---

# Extending Pi

Help the user choose what to build, scaffold the right artifact, and package it when useful.

This skill is intentionally **not** an API reference. Pi's docs, examples, and installed TypeScript types are the source of truth for exact signatures and current behavior.

## Core principle: choose a public extension point first, patch last

Pi has multiple public extension points: Agent Skills, context files, prompt templates, themes, packages, model configuration, provider extensions, settings, and TypeScript extensions. Assume one of those is the right answer until proven otherwise; do not jump straight to a TypeScript extension or Pi internal patch.

## What to build

| Goal | Build a… | Key files / locations | Detailed source of truth |
|------|----------|-----------------------|--------------------------|
| Teach an agent a workflow, domain, or how to use a tool/API/CLI | **Agent Skill** | `SKILL.md` plus optional `scripts/`, `references/`, `assets/` in `.agents/skills/`, `.pi/skills/`, or a package | Read `skill-creator/SKILL.md` and Pi docs `docs/skills.md` |
| Change Pi runtime behavior, add a typed tool, command, keybinding, event hook, UI, resource loader, provider, renderer, safety gate, or session behavior | **Extension** | TypeScript extension file in `.pi/extensions/`, `~/.pi/agent/extensions/`, or a Pi package | Read Pi docs `docs/extensions.md` fully plus relevant `examples/extensions/` code first |
| Reuse a prompt pattern with variables | **Prompt template** | Markdown file in `.pi/prompts/`, `~/.pi/agent/prompts/`, or a package | Read `docs/prompt-templates.md` |
| Set project-wide or user-wide instructions | **Context file** | `AGENTS.md`, `CLAUDE.md`, `SYSTEM.md`, or `APPEND_SYSTEM.md` as appropriate | Read the README Context Files / System Prompt sections |
| Change Pi's appearance | **Theme** | JSON theme in `.pi/themes/`, `~/.pi/agent/themes/`, or a package | Read `docs/themes.md` |
| Add or route models/providers | **models.json** or a **provider extension** | `~/.pi/agent/models.json` for supported APIs; extension for OAuth, dynamic discovery, or custom streaming | Read `docs/models.md` and `docs/custom-provider.md` |
| Share any of the above | **Pi package** | `package.json` with a `pi` key or conventional `extensions/`, `skills/`, `prompts/`, `themes/` directories | Read `docs/packages.md` |

## Behavior-change triage

Use this before touching Pi internals:

1. **State the desired user-visible behavior** in one sentence.
2. **Choose the lightest artifact** from the table above. Ask whether the need is instructions, configuration, a reusable package, a runtime hook/tool/UI, or a core bug fix.
3. **Read the current docs for the chosen surface.** Use the table's source-of-truth column; this skill should route you, not replace the docs.
4. **Inspect a relevant working example** when one exists and adapt that pattern where possible.
5. **If the request appears to require a Pi internal patch, stop and follow the patch policy below before writing code.** A patch should be the rare exception after the public-extension-point audit fails with concrete evidence.

## Agent Skill terminology

Use **Agent Skill** / **Agent Skills** when referring to the artifact, rather than client-specific names. Skills follow the Agent Skills standard and can be used by multiple agent clients. It is fine to say "Pi loads Agent Skills from…" when discussing Pi-specific discovery paths.

## Agent Skill vs Extension

If instructions plus normal tools are enough, prefer an **Agent Skill**. If the harness itself must change behavior, prefer an **Extension**.

Examples:

- "Pi should know our deploy process" → **Agent Skill** (workflow instructions and maybe helper scripts)
- "Pi should confirm before `rm -rf`" → **Extension** (intercept tool calls)
- "Pi should use Brave Search" → **Agent Skill** if a CLI/script plus instructions is enough; **Extension** if it needs a typed tool, custom UI, or runtime integration
- "Pi should have a structured `db_query` tool" → **Extension**
- "Pi should change the footer, add plan mode, add subagents, or alter compaction" → **Extension**

## TypeScript extension workflow

Use this when the chosen artifact is a Pi TypeScript extension or provider extension.

Agents often miss existing Pi extension points by reading only the first matching section or doing a heading search. Do the full extension audit:

1. **Read `docs/extensions.md` fully.** Extension capabilities are spread across hooks, tools, commands, keybindings, resource loaders, renderers, session/compaction events, settings, and linked docs.
2. **Follow relevant linked docs** for the surface you are changing: `docs/tui.md`, `docs/themes.md`, `docs/models.md`, `docs/custom-provider.md`, `docs/packages.md`, `docs/keybindings.md`, `docs/session-format.md`, or `docs/compaction.md`.
3. **Read `examples/extensions/README.md` and at least one matching example** under `examples/extensions/`. Copy current structure rather than inventing from memory.
4. **Map the request to a current extension capability**: events, tools, commands, shortcuts, flags, UI, custom rendering, resource discovery, model/provider registration, session/compaction hooks, tool operations, or packaging.
5. **Inspect installed types/source if docs or examples are ambiguous** rather than guessing API names or signatures. Useful starting points include `dist/core/extensions/types.d.ts`, `dist/core/index.d.ts`, and the matching `src/` files when available.
6. **Build as an extension or package unless the audit produces concrete evidence that no public extension point exists.** If no public route works, stop and follow the patch policy before writing code.

## Patch policy

Patch-level changes are extremely rare. They are appropriate only for core bugs, truly missing primitives, or behavior that genuinely cannot be expressed through public Pi extension points. Pi maintainers receive many AI-generated PRs; protect their time by avoiding speculative patches and only proposing changes you understand.

Before working on a patch:

1. Read upstream contributor guidance in `earendil-works/pi`: `CONTRIBUTING.md` and `AGENTS.md`.
2. Write down the desired behavior, the public extension points considered, the docs/examples/types/source inspected, and why each public route fails.
3. Prefer the smallest public extension API addition when the behavior should be user-extensible; otherwise propose the minimal core fix.
4. Ensure you can explain the code path, edge cases, tests, and interaction with the rest of Pi. If you cannot explain it clearly, do not patch.

## Quick-start steps

1. **Pick the artifact type** from the table above.
2. **Do the behavior-change triage** for any Pi behavior change before touching internals.
3. **For TypeScript extensions, complete the extension workflow.**
4. **Scaffold from current docs/examples**, not from stale snippets in this skill.
5. **Validate locally**:
   - Agent Skills: load with `pi --no-skills --skill /path/to/skill` or invoke `/skill:name`; if it does not trigger, check `name` and `description` frontmatter.
   - Extensions: test with `pi -e ./path/to/extension.ts`; for iterative work, put the extension in `.pi/extensions/` or `~/.pi/agent/extensions/` so `/reload` picks it up.
   - Themes/prompts/packages/models: use the relevant docs' validation/loading path, then `/reload` or restart where required.
6. **Package and share** when the result should be reusable: use `package.json` with a `pi` manifest or conventional resource directories, then test with `pi install ./path` or a git/npm source.