Authoring your own

If nothing in the catalog fits, build it. Pi is designed so you can extend it — or even ask Pi to extend itself — without forking. This page is a quick starter; see the official docs linked throughout for depth.

Where things live

Drop files into conventional directories and run /reload:

Layer	Global	Project
Extensions	`~/.pi/agent/extensions/`	`.pi/extensions/`
Skills	`~/.pi/agent/skills/`	`.pi/skills/`
Prompts	`~/.pi/agent/prompts/`	`.pi/prompts/`
Themes	`~/.pi/agent/themes/`	`.pi/themes/`

Write a skill (no code)

A skill is a directory with a SKILL.md. Frontmatter gives it a name and a description the model uses to decide when to load it.

---
name: pr-review
description: Use when reviewing a pull request for bugs and security issues.
---
# PR Review

## Steps
1. Read the diff.
2. Flag bugs, security issues, and missing tests.
3. Summarize findings as a checklist.

Invoke with /skill:pr-review, or let the model load it automatically. Skills follow the Agent Skills standard; see the skills docs.

Write an extension (TypeScript)

Extensions are TypeScript modules with a default export that receives the extension API:

import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: 'wordcount',
    description: 'Count words in a string',
    // ...schema + handler
  });

  pi.registerCommand('hello', {
    description: 'Say hello',
    run: () => { /* ... */ },
  });

  pi.on('tool_call', async (event, ctx) => {
    // inspect or gate tool calls
  });
}

The default export may be async for one-time setup (e.g. fetching a model list before pi.registerProvider()). Extensions can add tools, commands, keyboard shortcuts, event handlers, providers, and TUI components. See the extensions docs and the examples directory.

Bundle as a package

Add a pi manifest to package.json (or rely on conventional directories):

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

Runtime dependencies must be under dependencies (git installs use npm install --omit=dev).

npm: publish with the pi-package keyword so it’s discoverable on npm and pi.dev/packages. Users install with pi install npm:<name>.
git: users can install straight from a repo with pi install git:github.com/you/repo.

See the packages docs for the full manifest and discovery rules.