# Pi Customization

> Pi coding agent customization — Themes, Keybindings, Prompt Templates, System Prompt overrides, and Settings. Use when configuring or modifying the visual appearance, UI colors, keyboard shortcuts, prompt templates, or the default system prompt behavior of the pi terminal agent. Use for "custom theme pi", "change keybindings", "modify system prompt", "SYSTEM.md", "APPEND_SYSTEM.md", "settings.jso…

- **Type:** Skill
- **Install:** `agentstack add skill-romiluz13-pi-agent-skills-pi-customization`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [romiluz13](https://agentstack.voostack.com/s/romiluz13)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [romiluz13](https://github.com/romiluz13)
- **Source:** https://github.com/romiluz13/pi-agent-skills/tree/main/pi-skills/pi-customization

## Install

```sh
agentstack add skill-romiluz13-pi-agent-skills-pi-customization
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Pi Customization

## Grounding

1. `pi-mono/packages/coding-agent/docs/themes.md` — theme JSON format (`name`, optional `vars`, required 51 `colors` tokens), locations (`~/.pi/agent/themes/*.json`, `.pi/themes/*.json`, packages, settings, CLI `--theme`), hot reload, color value formats.
2. `pi-mono/packages/coding-agent/docs/keybindings.md` — customization via `~/.pi/agent/keybindings.json`, namespaced action IDs (`tui.input.submit`, `tui.editor.cursorUp`, `app.interrupt`, etc.), key format (`modifier+key`), full action tables.
3. `pi-mono/packages/coding-agent/docs/prompt-templates.md` — Markdown snippets invoked via `/name`, locations (`~/.pi/agent/prompts/*.md`, `.pi/prompts/*.md`, packages), positional arguments (`$1`, `$2`, `$@`, `${@:N}`), YAML frontmatter with optional `description`.
4. `pi-mono/packages/coding-agent/README.md` — Context Files section for `.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, and `APPEND_SYSTEM.md`.
5. `pi-mono/packages/coding-agent/docs/settings.md` — the overall `settings.json` structure for tying these together.

## Invariants

- **Theme Format**: Themes define `name` (required, unique), optional `vars` for reusable color aliases, and all 51 `colors` tokens. There is no `type`, `ui`, `syntax`, or `borders` top-level key — everything is under `colors`. Loaded from `~/.pi/agent/themes/*.json` (global) and `.pi/themes/*.json` (project).
- **Keybinding Config**: Keybindings are configured in `~/.pi/agent/keybindings.json` (not `settings.json`). IDs are namespaced: `tui.input.submit` (submit), `tui.editor.cursorUp`, `app.interrupt`, etc. Run `/reload` to apply changes without restarting.
- **Prompt Template Arguments**: Templates use `$1`, `$2`, `$@`, `${@:N}` positional syntax — not `{variable}` or ``. The filename (minus `.md`) becomes the `/name` command.
- **System Prompt Override**: Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Use `APPEND_SYSTEM.md` to append instead of replace. Context files and skills are still appended after the override.

## Workflows

- **Create a Theme**: Copy `dark.json` from `packages/coding-agent/src/modes/interactive/theme/`, customize color values under the `colors` key, place it in `~/.pi/agent/themes/`, and select via `/settings` or `pi --theme `.
- **Override Keys**: Create or edit `~/.pi/agent/keybindings.json` mapping action IDs to key arrays (e.g., `"tui.input.submit": ["ctrl+enter"]`). Run `/reload` to apply.
- **Create a Prompt Template**: Write a `.md` file in `~/.pi/agent/prompts/` with optional YAML frontmatter (`description`); use `$1`, `$@` for arguments. Invoke with `/filename` in the editor.
- **Override the System Prompt**: Create `.pi/SYSTEM.md` in the project or `~/.pi/agent/SYSTEM.md` globally to replace the default system prompt. Use `APPEND_SYSTEM.md` at the same locations if you want to append custom instructions instead.

## Anti-patterns

- Do not hardcode keybindings into agent component source code — use the configurable namespaces from `keybindings.md`.
- Do not put keybindings in `settings.json` — keybindings have their own file (`~/.pi/agent/keybindings.json`).
- Do not use `{variable}` or `` syntax in prompt templates — the actual syntax is `$1`, `$@`, `${@:N}`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [romiluz13](https://github.com/romiluz13)
- **Source:** [romiluz13/pi-agent-skills](https://github.com/romiluz13/pi-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-romiluz13-pi-agent-skills-pi-customization
- Seller: https://agentstack.voostack.com/s/romiluz13
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.