Stefano Fiorini
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
# 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 for source authoring and manual copies, but it is not clean for package-discovered installs
|
|
because Pi requires the immediate parent directory of `SKILL.md` to match the skill frontmatter
|
|
`name`.
|
|
|
|
### 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, but the package-facing skill directories must be shaped like
|
|
`<skill-name>/SKILL.md`. That means the repo should preserve `skills/<family>/pi/` for editing and
|
|
expose a separate mirror such as `pi-package/skills/<skill-name>/` to Pi.
|
|
|
|
### 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.
|
|
- Package Pi skills through a separate mirror whose immediate directory names match the frontmatter `name` values.
|
|
- 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.
|