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

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.