15  Prompt Templates

15.1 Overview

Prompt templates are reusable markdown files that expand into fully-formed prompts when you invoke them as slash commands. They let you codify complex instructions, code review checklists, debugging procedures, or any repeated prompt pattern into a single command.

15.2 Template Locations

Prompt templates are discovered from:

Location	Scope	Trust Required
~/.pi/agent/prompts/*.md	Global (all projects)	No
.pi/prompts/*.md	Project-local	Yes
--prompt-template <path>	CLI override	N/A
Via packages	Installed by pi install	Per package

Additional paths via settings.json:

{
  "prompts": [
    "/path/to/prompts/dir"
  ]
}

Disable prompt template discovery with --no-prompt-templates.

15.3 Creating a Prompt Template

15.3.1 Basic Example

Create ~/.pi/agent/prompts/review.md:

Review the code changes in the current branch. Focus on:

1. **Correctness** — Are there logic errors or edge cases?
2. **Security** — Are there potential vulnerabilities?
3. **Performance** — Are there unnecessary allocations or slow patterns?
4. **Style** — Does the code follow project conventions?
5. **Tests** — Are changes adequately covered?

Use `git diff main` to see the changes. Provide structured feedback with file, line number, and severity.

Invoke it in Pi:

/review

Pi expands the template content and sends it as a user message.

15.3.2 Variable Expansion

Prompt templates support variable expansion using $VARIABLE or ${VARIABLE} syntax:

Create ~/.pi/agent/prompts/fix-issue.md:

Investigate and fix the issue described below.

## Issue

$ISSUE_DESCRIPTION

## Constraints

- Do not modify the public API
- Add or update tests as needed
- Follow the existing error handling pattern

## Steps

1. Read the relevant source files
2. Identify the root cause
3. Implement the fix
4. Run the test suite

When you invoke /fix-issue, Pi checks for the ISSUE_DESCRIPTION variable in:

1. Arguments passed to the command: /fix-issue The login button doesn't work on Safari
2. Environment variables
3. Interactive prompt (if not found above)

15.4 Template Discovery

Pi discovers templates by scanning the template directories for .md files. The filename (without extension) becomes the command name.

~/.pi/agent/prompts/
├── review.md          → /review
├── fix-issue.md       → /fix-issue
├── deploy.md          → /deploy
└── debug.md           → /debug

15.4.1 Naming Rules

• Lowercase letters and digits
• Hyphens to separate words
• No spaces or special characters
• .md extension required

15.5 Using Templates

15.5.1 Interactive Mode

Type / in the editor and start typing the template name:

/review
/fix-issue The login button doesn't work on Safari
/deploy --env staging

15.5.2 Command Arguments

Arguments after the template name are appended to the template content:

<!-- debug.md -->
Debug the following issue step by step:

1. Reproduce the issue
2. Identify the root cause
3. Propose a fix
4. Implement the fix
5. Verify the fix works

/debug The API returns 500 on POST /users

The argument text is appended to the expanded template before sending.

15.5.3 Non-Interactive Mode

pi -p "$(cat ~/.pi/agent/prompts/review.md)"

Or use the --prompt-template flag to load a specific template:

pi --prompt-template ./my-template.md -p "Additional context"

15.6 Template Content Guidelines

15.6.1 Be Specific

<!-- ❌ Too vague -->
Help me with the database.

<!-- ✅ Specific and actionable -->
Review the PostgreSQL schema in `db/schema.sql`. Check for:

1. Missing indexes on foreign keys
2. Proper use of constraints (NOT NULL, UNIQUE, CHECK)
3. Naming convention compliance (snake_case tables and columns)
4. Potential performance issues with large tables

Report findings as a markdown table.

15.6.2 Include Context

## Context

This project uses:
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL with Prisma ORM
- Testing: Vitest
- Styling: Tailwind CSS

## Task

$TASK_DESCRIPTION

## Requirements

- Follow the existing code patterns
- Add JSDoc comments for new functions
- Ensure all tests pass before finishing

15.6.3 Reference Files

Templates can reference files that the agent should read:

Review the pull request. Before starting, read:

1. `.github/PULL_REQUEST_TEMPLATE.md` — for review criteria
2. `CONTRIBUTING.md` — for coding standards
3. `AGENTS.md` — for project-specific rules

Then review the changes with `git diff main...HEAD`.

15.7 Advanced Patterns

15.7.1 Conditional Content

Use markdown comments for conditional sections that the agent interprets:

Debug the issue: $DESCRIPTION

<!-- If the issue is related to performance: -->
- Profile the relevant code path with `node --prof`
- Analyze the output for hot functions
- Check for unnecessary re-renders or recomputations

<!-- If the issue is related to correctness: -->
- Write a minimal reproduction case
- Add logging to trace the execution path
- Check edge cases and boundary conditions

15.7.2 Multi-Step Workflows

Perform a comprehensive security audit. Work through each step:

## Step 1: Dependency Audit

Run `npm audit` and review vulnerabilities.

## Step 2: Code Scan

Check for:
- SQL injection (especially in raw queries)
- XSS vulnerabilities (unescaped output)
- CSRF token handling
- Authentication and authorization checks
- Sensitive data exposure (logs, errors, API responses)

## Step 3: Configuration Review

Check:
- Environment variable handling
- CORS configuration
- Rate limiting
- HTTPS/TLS settings

## Step 4: Report

Generate a security audit report with severity levels.

15.8 Sharing Templates

15.8.1 Via Packages

Include prompt templates in a pi package:

// package.json
{
  "name": "@myorg/pi-templates",
  "pi": {
    "prompts": [
      "prompts/*.md"
    ]
  }
}

Install with:

pi install npm:@myorg/pi-templates

15.8.2 Via Git

Store templates in a git repository and install:

pi install git:github.com/myorg/pi-templates@v1

15.8.3 Manual Sharing

Copy .md files to ~/.pi/agent/prompts/ or .pi/prompts/.

Tip

Combine prompt templates with skills for powerful workflows. Templates define the prompt; skills define the capability. For example, a code-review template can invoke a code-review skill that includes scripts and reference docs.