Skills & Prompt Templates

Lesson 5: Skills & Prompt Templates

Two complementary ways to package knowledge for the agent. Skills are self-contained capability packages loaded on demand; prompt templates are Markdown snippets that expand into full prompts when you type /name. Pi can even create both for you — just ask it.

Skills: the Agent Skills standard

Pi implements the open Agent Skills standard (agentskills.io), which means skills written for other harnesses mostly work here. A skill is a directory with a SKILL.md file: YAML frontmatter (name, description) plus body content — setup instructions, workflows, helper scripts, reference docs.

~/.pi/agent/skills/        # global
~/.agents/skills/          # global, shared across agents
.pi/skills/                # project-local (after trust)
.agents/skills/            # project-local, shared

# invoke with:
/skill:name

Skills are loaded on demand: pi keeps their description in the model's view and only injects the full content when the task matches. That is their superpower — capability without constant context cost. The docs also cover skill repositories for distributing collections.

Prompt templates

A template is a Markdown file whose filename becomes a slash command. Type /review and review.md expands inline into the editor. Frontmatter can add a description and an argument-hint that renders in autocomplete:

---
description: Review staged git changes
argument-hint: "<PR-URL>"
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps

Locations: ~/.pi/agent/prompts/*.md (global), .pi/prompts/*.md (project), package prompts/ dirs, a prompts array in settings, or --prompt-template <path> flags. Discovery is non-recursive; subdirectories need explicit registration. --no-prompt-templates disables them.

Template arguments

$1 $2 ...          positional args
$@ / $ARGUMENTS    all args joined
${1:-default}      arg with fallback
${@:-default}      all args with fallback
${@:N}             args from position N
${@:N:L}           L args starting at N

# usage: /component Button "click handler" "disabled support"
---
description: Create a component
---
Create a React component named $1 with features: $@

Further Reading

• Pi Skills — locations, structure, SKILL.md format
• Prompt Templates — format, arguments, loading rules
• Agent Skills — the open standard pi implements