Guide for extending Pi — decide between skills, extensions, prompt templates, themes, context files, or custom models, then create and package them.
SkillScore100Maintained
Automatic
◆AI Engineer pack
Last verified 8/29/2026
What it changes
Passed 22 of 22 test cases with the skill, and 10 of 22 without it.
Without skill45%
With skill100%
Checks it passed that the model alone missed
Specifies .pi/agent/
Mentions registerTool
References docs/themes.md
and 11 more in the full report
12 fixed10 passed either way0 still failing0 broke
Pass-rate lift
+55 pp
Tokens
-56%
Agent turns
0%
Response time
-73%
Model gemini-3.6-flashMeasured 8/29/2026v122 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 12 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 12
Prompt
If I don't place AGENTS.md at the project root, what is the alternative nested directory path inside the project where Pi looks for agent context files?
What was checked, without and with the skill
Checked
Without skill
With skill
Specifies .pi/agent/
Missed
Passed
case-15 · gemini-3.6-flash · 8/29/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md25 linessingle file
Extending Pi
Help the user decide what to build and where to find guidance.
What to build
Goal
Build a…
Where
Teach Pi a workflow or how to use a tool/API/CLI
Skill
Read skill-creator/SKILL.md for detailed guidance
Give Pi a new tool, command, or runtime behavior
Extension
Read Pi docs: docs/extensions.md
Reuse a prompt pattern with variables
Prompt template
Read Pi docs: docs/prompt-templates.md
Set project-wide coding guidelines
Context file
AGENTS.md in project root or .pi/agent/ — just markdown
Change Pi's appearance
Theme
Read Pi docs: docs/themes.md
Add a model or provider
Custom model
Read Pi docs: docs/models.md (JSON) or docs/custom-provider.md (extension)
Share any of the above
Package
Read Pi docs: docs/packages.md
Skill vs Extension — the fuzzy boundary
If bash + instructions can do it, prefer a skill (simpler, no code to maintain). If you need event hooks, typed tools, UI components, or policy enforcement, use an extension.
Examples:
"Pi should know our deploy process" → Skill (workflow instructions)
"Pi should confirm before rm -rf" → Extension (event interception)
"Pi should use Brave Search" → Skill (instructions + CLI scripts)
"Pi should have a structured db_query tool" → Extension (registerTool)