Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

Browse Source
This commit is contained in:
Stefano Fiorini
2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PI-RESEARCH.md
+24 -9
View File
@@ -2,7 +2,8 @@
## 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.
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`.
@@ -32,11 +33,15 @@ Important discovery details from the skills docs:
- 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`.
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`.
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:
@@ -46,11 +51,16 @@ Relevant package behaviors:
- 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.
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 `~`.
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:
@@ -68,18 +78,23 @@ Pi extensions are TypeScript modules that can:
- 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.
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.
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.
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
- 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