Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

Pi can create prompt templates for you. Just ask it to build one for your workflow.
Prompt templates are Markdown snippets that expand into full prompts. Type /name in the editor to invoke a template, where name is the filename without .md.

​
Template Locations

Pi loads prompt templates from: Global:
  • ~/.pi/agent/prompts/*.md
Project:
  • .pi/prompts/*.md
Packages:
  • prompts/ directories in pi packages
  • pi.prompts entries in package.json
Settings:
  • prompts array with files or directories
CLI:
  • --prompt-template <path> (repeatable)
Disable discovery with --no-prompt-templates.

​
Template Format

---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps
Rules:
  • The filename becomes the command name. review.md becomes /review
  • description is optional. If missing, the first non-empty line is used
  • Everything after the frontmatter is the template content

​
Basic Usage

Type / followed by the template name: 
/review
The template content replaces the /review text in the editor, then you can submit or edit further.

​
Arguments

Templates support positional arguments and simple slicing:
​
$1, $2, ...
string
Positional arguments
​
$@ or $ARGUMENTS
string
All arguments joined with spaces
​
${@:N}
string
Arguments from the Nth position (1-indexed)
​
${@:N:L}
string
L arguments starting at position N

​
Example: Component Template

File: ~/.pi/agent/prompts/component.md 
---
description: Create a React component
---
Create a React component named $1 with features: ${@:2}

Requirements:
- TypeScript
- Proper types
- Tests with vitest
Usage: 
/component Button "onClick handler" "disabled support" "loading state"
Expands to: 
Create a React component named Button with features: onClick handler disabled support loading state

Requirements:
- TypeScript
- Proper types
- Tests with vitest

​
Examples

​
Code Review

File: ~/.pi/agent/prompts/review.md 
---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps
- Performance problems
- Code style inconsistencies

Provide actionable feedback.
Usage: 
/review

​
Test Generation

File: ~/.pi/agent/prompts/test.md 
---
description: Generate tests for a function or module
---
Generate comprehensive tests for $1 using $2.

Include:
- Happy path tests
- Edge cases
- Error handling
- Mocks where appropriate

Use descriptive test names.
Usage: 
/test src/utils/parser.ts vitest

​
Documentation

File: ~/.pi/agent/prompts/doc.md 
---
description: Add documentation to code
---
Add comprehensive documentation to $1.

Include:
- JSDoc/TSDoc comments for all public APIs
- Parameter descriptions
- Return value descriptions
- Usage examples
- Edge cases and gotchas
Usage: 
/doc src/api/users.ts

​
Refactoring

File: ~/.pi/agent/prompts/refactor.md 
---
description: Refactor code with specific goal
---
Refactor $1 to $2.

Objectives:
- Maintain existing functionality
- Improve code quality
- Keep tests passing
- Follow project conventions

Explain the changes you make.
Usage: 
/refactor src/components/Form.tsx "use React Hook Form"

​
Bug Analysis

File: ~/.pi/agent/prompts/debug.md 
---
description: Debug an issue
---
Debug this issue: $@

Steps:
1. Identify the root cause
2. Explain why it happens
3. Propose a fix
4. Consider edge cases
5. Suggest prevention strategies
Usage: 
/debug "Login fails when username contains spaces"

​
Advanced Usage

​
Conditional Content

Use argument presence to include conditional content: 
---
description: Create API endpoint
---
Create a $1 API endpoint at $2${3:+ with authentication}.

Implement:
- Request validation
- Error handling
- Response formatting
${3:+- Authentication checks}
The ${3:+text} syntax includes with authentication only if argument 3 is provided.

​
Multiple Files

Reference multiple files: 
---
description: Compare implementations
---
Compare the implementations in:
- $1
- $2

Highlight:
- Differences in approach
- Pros and cons of each
- Recommendation for which to use
Usage: 
/compare @src/v1/parser.ts @src/v2/parser.ts

​
Loading Rules

Template discovery in prompts/ is non-recursive. Only files directly in the directory are loaded.
For templates in subdirectories, add them explicitly: 
{
  "prompts": [
    "./prompts",
    "./prompts/team",
    "./prompts/personal"
  ]
}
Or use a pi package manifest: 
{
  "pi": {
    "prompts": [
      "./prompts/**/*.md"
    ]
  }
}

​
Naming Collisions

If multiple templates have the same name:
  1. Project templates override global templates
  2. Later paths in settings override earlier ones
  3. A warning is shown in verbose startup

​
Creating Templates

1

Create File

mkdir -p ~/.pi/agent/prompts
vim ~/.pi/agent/prompts/review.md
2

Add Frontmatter

---
description: Review code for issues
---
3

Write Template

Review the following for:
- Security issues
- Performance problems
- Best practices
4

Test

pi
/review

​
Sharing Templates

Package templates for others:
1

Create Package

{
  "name": "my-prompts",
  "keywords": ["pi-package"],
  "pi": {
    "prompts": ["./prompts"]
  }
}
2

Add Templates

my-prompts/
├── package.json
└── prompts/
    ├── review.md
    ├── test.md
    └── doc.md
3

Publish

npm publish
4

Users Install

pi install npm:my-prompts
See Pi Packages for full details.

​
Best Practices

Be Specific

Write focused templates for specific tasks rather than generic prompts

Use Arguments

Leverage $1, $2, $@ for flexibility without creating many similar templates

Include Context

Provide enough context in the template for the model to understand requirements

Show Examples

Include example usage in comments or description for other users

Keep It Short

Templates should be reusable snippets, not complete instructions. Save complex workflows for Skills.

Name Clearly

Use descriptive filenames that clearly indicate the template’s purpose

​
Templates vs Skills

Use templates for:
  • Quick prompts and reminders
  • Common review patterns
  • Standard questions
  • Short, reusable text
Use skills for:
  • Multi-step workflows
  • External tool integration
  • Complex setup procedures
  • On-demand documentation
See Skills for more information.

​
Next Steps

Skills

Create Agent Skills for complex workflows

Pi Packages

Package and share templates via npm or git

Build docs developers (and LLMs) love

Get started for freeTalk to us