Pi Agent Prompt Template
Prompt templates are predefined Markdown snippets that can be expanded into full prompts with a short command, improving efficiency for repetitive work.
Template Overview
The way prompt templates work is simple:
- Create a Markdown file to define the template content
- Type in the editor/template-nameto invoke it
- The template automatically expands and fills into the editor
Templates support parameter substitution, allowing the same template to be used in different specific scenarios.
Creating a Template
Templates are Markdown files with YAML Frontmatter.
The file name (without .md) is the template's command name.
Create a code review template:
Example
description: Review the current git staged changes
---
Review the changes in the staging area (git diff --cached), focusing on:
- Potential bugs and logical errors
- Security issues
- Error handling and edge cases
- Performance issues
Save to~/.pi/agent/prompts/review.mdThen type in the editor/reviewto expand and use it.
Template Location
Pi Agent looks for templates in several fixed locations, each with a different scope.
| Location | Scope |
|---|---|
| ~/.pi/agent/prompts/*.md | Global templates, available to all projects |
| .pi/prompts/*.md | Project templates, loaded only after the project is trusted |
| The prompts/ directory in Pi Packages | Templates in the package |
| --prompt-template path | Temporary load from command line |
Template discovery isnon-recursiveTemplates in prompts/ subdirectories will not be automatically loaded.
If templates are placed in subdirectories, you need to explicitly add the path to the prompts array in settings.json.
Parameter System
Templates support a rich parameter system, allowing the same template to adapt to different scenarios:
| Syntax | Meaning | Example |
|---|---|---|
| $1, $2, $3... | Positional parameters | $1 represents the first parameter |
| $@ or $ARGUMENTS | Concatenation of all parameters | Join all parameters with spaces |
| ${1:-default} | Parameter with a default value | Use the parameter if it exists and is non-empty, otherwise use the default value |
| ${@:N} | Start from the Nth parameter | ${@:2} takes all parameters starting from the 2nd |
| ${@:N:L} | Take L parameters starting from the Nth | ${@:2:3} takes parameters 2 through 4 |
$ARGUMENTS concatenates all parameters as-is, suitable for templates that need only a whole block of text:
Example
description: Translate a piece of Chinese into natural English
argument-hint: "<Chinese to translate>"
---
Translate the following content into natural English, output only the translation:
$ARGUMENTS
Save as~/.pi/agent/prompts/translate.mdThen use/translate to translate this passage into Englishto invoke.
Template Example with Parameters
The template below combines positional parameters and trailing parameters, suitable for inputs like "type + name + supplementary description".
Example
description: Create a component using the specified framework
argument-hint: "<framework> <component-name> [feature description]"
---
Use $1 to create a $2 component, with features including: ${@:3}
$1 takes the first parameter as the framework, $2 takes the second parameter as the component name.
${@:3} represents all content starting from the third parameter, used to carry scattered feature descriptions.
Usage:
/component React Button "onClick 事件处理" "disabled 状态支持" "loading 加载状态"
Expanded result:
使用 React 创建一个 Button 组件，功能包括：onClick 事件处理 disabled 状态支持 loading 加载状态
Default Value Example
When parameters are missing, default values serve as a fallback, so the template works normally even when invoked without parameters.
Example
description: Summarize the current project status
---
Summarize the main changes and status of the current project in ${1:-5} bullet points.
Save to~/.pi/agent/prompts/summarize.mdThen use/summarizeto invoke.
Using/summarizeoutputs 5 bullet points by default.
Using/summarize 10outputs 10 bullet points.
The expanded results of the two invocations compare as follows:
/summarize → 用 5 个要点总结当前项目的主要变更和状态。 /summarize 10 → 用 10 个要点总结当前项目的主要变更和状态。
argument-hint Parameter Hint
Setting in Frontmatterargument-hintcan help users understand the parameters the template needs:
Example
description: Review PR from URL, analyze code and issues
argument-hint: "<PR-URL>"
---
Review the code changes in the following PR, focusing on security and performance issues: $1
In the autocomplete dropdown menu, this template will display as:
→ pr <PR-URL> — 从 URL 审查 PR，分析代码和问题
Save to~/.pi/agent/prompts/pr-review.mdThen use/pr-review https://github.com/example/repo/pull/12to invoke.
Use<angle brackets>for required parameters,[square brackets]for optional parameters.
Practical Template Examples
The following three templates cover the three most common types of requests in daily development, and can be copied and adjusted as needed.
Git Commit Message Generation
The following template generates commit messages according to the Conventional Commits specification.
Example
description: Generate a conventional commit message based on git diff
---
Review the content of git diff --cached and generate a conventional git commit message.
Follow the Conventional Commits specification, format: type(scope): description
Types include: feat, fix, refactor, docs, test, chore
Save to~/.pi/agent/prompts/commit.mdAfter that, stage your changes and use/committo invoke.
Code Refactoring Request
The following template breaks down refactoring goals into clear check items, preventing the AI from only changing formatting without touching the structure.
Example
description: Refactor the specified code module
argument-hint: "<file path or module name>"
---
Refactor the code of $1, goals:
1. Improve code readability
2. Eliminate duplicate code
3. Improve error handling
4. Keep existing functionality unchanged
Before making changes, please explain your refactoring plan.
Save to~/.pi/agent/prompts/refactor.mdThen use/refactor src/utils/date.tsto invoke.
Bug Fix Request
The following template forces the AI to troubleshoot in fixed steps, reducing the tendency to "modify code immediately".
Example
description: Systematically troubleshoot and fix the specified bug
argument-hint: "<Bug description>"
---
I need you to help me troubleshoot and fix the following bug: $1
Please follow these steps:
1. First understand the expected and actual behavior of the bug
2. Find the relevant code files
3. Analyze possible causes
4. Propose a fix plan
5. Implement the fix
6. Verify the fix is correct
Explain your findings and reasoning at each step.
Save to~/.pi/agent/prompts/fix-bug.mdthen, use/fix-bug The list does not refresh after loginto call.
Template Loading Rules
Template discovery and loading follow the rules below. If you are troubleshooting "template does not appear," check here first.
| Rule | Description |
|---|---|
| Non-recursive discovery | Template discovery in the prompts/ directory isnon-recursive; templates in subdirectories will not be automatically discovered |
| Subdirectories must be explicitly declared | When you need to load templates in a subdirectory, explicitly add the path to the prompts array in settings.json |
| description fallback | Ifdescriptionis empty, Pi Agent will use the first non-empty line of the file as the description |
| Disable automatic discovery | Through--no-prompt-templatesautomatic discovery is disabled, but templates explicitly specified with--prompt-templatewill still be loaded |
Other extensionsAfter entering /template name, if it does not appear in the completion list, first confirm whether the file is in the prompts/ root directory.
Project templates placed in .pi/prompts/ must also pass the project trust check first, otherwise they will not be loaded either.