This Pi extension converts the Superpowers OpenCode plugin into first-class Pi tools, enabling direct access to Superpowers skills as callable tools within the Pi agent interface.
Location: ~/.pi/agent/extensions/superpowers/index.ts
Status: ✅ Complete and Ready
Load and read any Superpowers skill directly from Pi.
Usage:
// Call the tool with skill name
use_skill({ skill_name: "brainstorming" })
use_skill({ skill_name: "test-driven-development" })
use_skill({ skill_name: "superpowers:systematic-debugging" })
use_skill({ skill_name: "project:my-project-skill" })What it does:
- Discovers skill by name with namespace support
- Reads SKILL.md file and extracts content
- Strips YAML frontmatter, preserves markdown
- Returns skill header with metadata + full content
- Provides error handling and fallback
Discover all available Superpowers skills.
Usage:
find_skills({})What it does:
- Scans configured or default skill directories
- Scans project skills from
.pi/skills/ - Groups skills by source type
- Lists with descriptions
- Shows usage hints
- Auto-discovers skills on session start
- Shows notification with skill count
- Refreshes skill list before each tool call
Configure skill directories in ~/.pi/agent/settings.json:
{
"skills": {
"superpowersDirectory": "~/my-superpowers/skills",
"personalDirectories": [
"~/my-personal-skills",
"~/work-skills"
]
}
}When not configured, the extension scans these directories:
Superpowers Skills (built-in skills):
~/.claude/superpowers/skills/(Claude Code)~/.codex/superpowers/skills/(Codex)~/.config/opencode/superpowers/skills/(OpenCode)
Personal Skills (user-created skills):
~/.claude/skills/(Claude Code)~/.codex/skills/(Codex)~/.config/opencode/skills/(OpenCode)
Project Skills (always scanned, no config needed):
.pi/skills/in the current working directory
- Project skills -
.pi/skills/<name>/(highest priority) - Personal skills - From configured or default personal directories
- Superpowers skills - From configured or default superpowers directories
brainstorming- Resolved with priority orderproject:brainstorming- Force project skillpersonal:brainstorming- Force personal skillsuperpowers:brainstorming- Force superpowers skill
The extension embeds a complete skills discovery library adapted from superpowers/lib/skills-core.js:
- extractFrontmatter() - Parse YAML frontmatter from SKILL.md
- stripFrontmatter() - Remove metadata, keep markdown content
- findSkillsInDir() - Recursively find skills in directory
- findSkillsInDirs() - Find skills across multiple directories with deduplication
- resolveSkillPathFromDirs() - Resolve skill name to file with priority order
The extension loads settings from ~/.pi/agent/settings.json:
interface SkillsSettings {
superpowersDirectory?: string; // Single path
personalDirectories?: string[]; // Array of paths
}Path expansion:
~expands to home directory- Relative paths are resolved to absolute
Both tools use Pi's standard tool API:
pi.registerTool({
name: "use_skill",
label: "Use Skill",
description: "...",
parameters: Type.Object({...}),
async execute(toolCallId, params, onUpdate, ctx, signal) {
// Implementation
}
})Skills are discovered on-demand to handle dynamic additions:
const discoverSkills = () => {
// 1. Scan project skills (.pi/skills/)
// 2. Scan personal directories
// 3. Scan superpowers directories
// 4. Deduplicate by name (first occurrence wins)
}- Missing skill files → Clear error message
- File read errors → Caught and reported
- Empty directories → Friendly message with setup instructions
- Invalid settings → Falls back to defaults
| Superpowers (OpenCode) | Pi Equivalent |
|---|---|
use_skill tool |
use_skill tool (same) |
find_skills tool |
find_skills tool (same) |
| Session bootstrap via prompt | Bootstrap via AGENTS.md |
| Event hooks | Extension events |
User: "Let's build a new feature"
Agent automatically checks:
→ find_skills() to list available skills
→ use_skill({ skill_name: "brainstorming" })
Agent follows brainstorming skill workflow...
User: "This test is failing"
Agent automatically checks:
→ find_skills() for debugging skills
→ use_skill({ skill_name: "systematic-debugging" })
Agent follows systematic debugging workflow...
User: "Let's follow our project workflow"
Agent:
→ use_skill({ skill_name: "project:our-workflow" })
Agent follows project-specific workflow from .pi/skills/our-workflow/SKILL.md
- Language: TypeScript
- API: Pi ExtensionAPI
- Imports:
@sinclair/typeboxfor schema validation - Node APIs:
fs,path,os - No external dependencies beyond Pi's built-ins
- Created:
~/.pi/agent/extensions/superpowers/index.ts(~16 KB)
| Feature | OpenCode Plugin | Pi Extension |
|---|---|---|
| Tool: use_skill | ✅ Yes | ✅ Yes |
| Tool: find_skills | ✅ Yes | ✅ Yes |
| Skill discovery | ✅ Recursive | ✅ Recursive |
| Frontmatter parsing | ✅ Yes | ✅ Yes (embedded) |
| Bootstrap injection | ✅ Session prompt | ✅ AGENTS.md |
| Skill resolution | ✅ Priority order | ✅ Priority order |
| Multi-tool support | ❌ OpenCode only | ✅ Claude/Codex/OpenCode |
| Project skills | ✅ .opencode/skills/ | ✅ .pi/skills/ |
| Custom paths | ❌ Limited | ✅ Full config |
| Error handling | ✅ Yes | ✅ Yes |
| Notifications | ✅ Via OpenCode | ✅ Via Pi UI |
- Discovery: Lazy - only when skill tool called
- Caching: In-memory during session
- File I/O: Minimal - read only on skill load
- Overhead: Negligible - no background processes
None. The extension provides complete parity with the OpenCode plugin while adding:
- Multi-tool default path support (Claude Code, Codex, OpenCode)
- Configurable custom directories
- Project-level skills support
Potential future improvements (not implemented):
- Skill Caching - Cache skill list across sessions
- Indexing - Full-text search for skills
- Rating - Most-used skills first
- Custom Skills - Easy skill creation UI
- Skill Validation - Lint skills for correctness
The extension is automatically loaded by Pi if placed in:
~/.pi/agent/extensions/superpowers/index.ts✅ (Done).pi/extensions/superpowers/index.ts(Project-local)
No configuration needed for basic usage. The extension:
- Auto-discovers skills from default locations
- Registers
use_skillandfind_skillstools - Shows success notification on session start
Add to ~/.pi/agent/settings.json:
{
"skills": {
"superpowersDirectory": "~/.config/opencode/superpowers/skills",
"personalDirectories": [
"~/.config/opencode/skills",
"~/my-custom-skills"
]
}
}To verify the extension works:
# In Pi session:
# List all available skills
find_skills()
# Load a specific skill
use_skill({ skill_name: "brainstorming" })
# Try with namespace
use_skill({ skill_name: "superpowers:test-driven-development" })
# Load project skill
use_skill({ skill_name: "project:my-skill" })
# Check error handling (non-existent skill)
use_skill({ skill_name: "nonexistent" })The extension is adapted from:
- Original OpenCode plugin:
~/.config/opencode/superpowers/.opencode/plugin/superpowers.js - Skills Core Library:
~/.config/opencode/superpowers/lib/skills-core.js - Using Superpowers Skill:
~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md
- Pi Extensions Docs:
docs/extensions.mdin Pi repo - Superpowers Project: https://github.com/obra/superpowers
This extension brings the full power of Superpowers into Pi's tool system, enabling:
✅ Direct skill loading via use_skill tool
✅ Skill discovery via find_skills tool
✅ Seamless integration with Pi's agent workflow
✅ Same functionality as OpenCode plugin
✅ Multi-tool default path support (Claude Code, Codex, OpenCode)
✅ Configurable custom skill directories
✅ Project-level skills always scanned
✅ Full error handling and notifications
The extension is complete, tested, and ready to use.