# PI RESEARCH

## Scope

This document records the pi-specific findings that drive the `pi` variants in this repo. It is intentionally source-backed so later skill work does not rely on memory or assumptions.

Checked on `2026-04-23`.

## Primary Sources

- [pi skills documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
- [pi packages documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/packages.md)
- [pi extensions documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)
- [pi settings documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/settings.md)
- [pi coding-agent README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)

## Findings

### Skill Discovery

Pi loads skills from multiple places:

- global skill roots: `~/.pi/agent/skills/` and `~/.agents/skills/`
- project skill roots: `.pi/skills/` and `.agents/skills/`
- package resources: `skills/` convention directories or `pi.skills` entries in `package.json`
- settings-provided skill paths
- explicit `--skill <path>` CLI arguments

Important discovery details from the skills docs:

- directories containing `SKILL.md` are discovered recursively
- top-level `.md` files are loaded as skills in pi-native roots like `.pi/skills/`
- per the upstream skills docs, top-level `.md` files are ignored in `.agents/skills/`

Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly, both for local copies and for package-based installs.

### Package Support

Pi packages are a first-class distribution path. The package docs say pi can load resources through conventional directories like `skills/`, or through explicit `pi` manifest entries in `package.json`.

Relevant package behaviors:

- `keywords: ["pi-package"]` makes packages show up in the gallery
- `pi.skills` can point at specific skill directories
- `files` allowlists should be used to keep tarballs tight
- installed pi packages can also ship `extensions/`, `prompts/`, and `themes/`
- when pi installs npm or git packages, it runs `npm install`

Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the pi resources.

### Settings And Path Overrides

Pi settings support `packages`, `extensions`, `skills`, `prompts`, and `themes`. In both `~/.pi/agent/settings.json` and `.pi/settings.json`, the `skills` array can point to local files or directories, and the docs explicitly allow absolute paths and `~`.

Implication for this repo:

- pi can consume repo-local resources without publishing a package
- users can point pi at shared roots like `~/.agents/skills`
- workflow skills can document deterministic helper paths and fall back to settings-driven installs when needed

### Extensions

Pi extensions are TypeScript modules that can:

- register custom tools
- register commands
- intercept lifecycle events and tool calls
- add UI interactions and custom components
- persist session state

The coding-agent README explicitly lists advanced behaviors like sub-agents, plan mode, permission gates, MCP integration, and git checkpointing as extension-capable areas.

Implication for this repo: extensions are a real opportunity for workflow-heavy skills, but they are optional for the initial skill port. The base skill variants should remain usable without any extension dependency.

### Cross-Harness Compatibility

The pi skills docs explicitly call out `~/.agents/skills/` as a supported global skill root, and describe adding Codex or Claude skill directories through settings when needed.

Implication for this repo:

- existing Superpowers installs exposed through `~/.agents/skills/` can already be visible to pi
- pi-specific skill variants still need their own instructions because pi does not share Codex's `update_plan`, plan-mode, or worktree assumptions

## Decisions Derived From Research

- Use `skills/<skill>/pi/` for all five skill families.
- Publish shared pi guidance in repo docs instead of burying pi assumptions inside each skill.
- Use one repo-level pi package in v1.
- Assess extensions explicitly, but defer them unless they provide clear v1 value beyond documentation and helper scripts.