Core concepts

Pi is intentionally minimal. Rather than baking in features, it exposes primitives you compose. There are four customization layers, plus the package format that bundles them.

The four layers

Extensions

TypeScript modules that extend Pi with custom tools, commands, keyboard shortcuts, event handlers, providers, and UI components. They have the deepest reach — most “big” features in this guide (sub-agents, plan mode, MCP, web search, permission gates) are extensions.

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: 'deploy', /* ... */ });
  pi.registerCommand('stats', { /* ... */ });
  pi.on('tool_call', async (event, ctx) => { /* ... */ });
}

Discovered from ~/.pi/agent/extensions/, .pi/extensions/, or a package.

Skills

Markdown capability packages following the Agent Skills standard. A skill is a directory with a SKILL.md file (YAML frontmatter + instructions, plus optional helper scripts). Skills load on demand — the model sees only names and descriptions until it needs one, so they add capability without busting the prompt cache (progressive disclosure).

~/.pi/agent/skills/my-skill/SKILL.md

# My Skill
Use this skill when the user asks about X.

## Steps
1. Do this
2. Then that

Invoke via /skill:name or let the model load them automatically. Discovered from ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, .agents/skills/, or a package. Pi can also reuse Claude Code / Codex skill directories.

Prompt templates

Reusable prompts as Markdown files. Type /name to expand the template into the editor; templates can take {{variables}}.

~/.pi/agent/prompts/review.md

Review this code for bugs, security, and performance. Focus on: {{focus}}

Themes

Color/UI theming for the interactive TUI. Built-ins are dark and light. Themes hot-reload — edit the active theme file and Pi applies it immediately.

Pi packages

A package bundles any combination of the four layers and is shared via npm or git. A package is just a package.json with a pi manifest (or conventional directories):

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

Find them on pi.dev/packages or via the pi-package keyword on npm.

Extension vs. skill: which do I pick?

Use a skill when…	Use an extension when…
You’re packaging instructions/workflow (markdown + maybe scripts)	You need new tools, commands, UI, or event hooks
You want on-demand, cache-friendly loading	You need to change Pi’s behaviour at runtime
No TypeScript required	You’re comfortable writing TypeScript
Examples: language/platform playbooks, review checklists	Examples: sub-agents, MCP, web search, permission gates

Many packages combine both — e.g. an extension that registers a tool plus a skill that tells the model when to use it.

How this guide is organized

The capability guides group packages by the problem they solve. Each guide surveys 2–3 popular alternatives with install commands, benefits, and drawbacks, then a short “which should I pick” recommendation. The comparison table lists everything at a glance.