mirror of
https://github.com/earendil-works/pi.git
synced 2026-06-18 15:54:04 +08:00
Andrés Vinueza
aa25726ebf
* feat(coding-agent,tui): support argument-hint frontmatter in prompt templates Parse argument-hint from prompt template frontmatter and display it in the autocomplete dropdown description, matching Claude Code's convention for custom commands. Frontmatter format: --- description: Code review argument-hint: "[file | #PR | PR-URL]" --- The hint renders in the description column of the autocomplete list: review [file | #PR | PR-URL] — Code review Closes #2761 * docs(coding-agent,tui): add argument-hint documentation, tests, and built-in hints - Document argument-hint frontmatter in prompt-templates.md with <required>/[optional] convention - Add argument-hint to built-in prompts: pr, is, wr - Expand tests: required/optional hints, missing hints, empty hints, special characters - Add changelog entries for coding-agent and tui
89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
> pi can create prompt templates. Ask it to build one for your workflow.
|
|
|
|
# Prompt Templates
|
|
|
|
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`.
|
|
|
|
## Locations
|
|
|
|
Pi loads prompt templates from:
|
|
|
|
- Global: `~/.pi/agent/prompts/*.md`
|
|
- Project: `.pi/prompts/*.md`
|
|
- Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
|
|
- Settings: `prompts` array with files or directories
|
|
- CLI: `--prompt-template <path>` (repeatable)
|
|
|
|
Disable discovery with `--no-prompt-templates`.
|
|
|
|
## Format
|
|
|
|
```markdown
|
|
---
|
|
description: Review staged git changes
|
|
---
|
|
Review the staged changes (`git diff --cached`). Focus on:
|
|
- Bugs and logic errors
|
|
- Security issues
|
|
- Error handling gaps
|
|
```
|
|
|
|
- The filename becomes the command name. `review.md` becomes `/review`.
|
|
- `description` is optional. If missing, the first non-empty line is used.
|
|
- `argument-hint` is optional. When set, the hint is displayed before the description in the autocomplete dropdown.
|
|
|
|
### Argument Hints
|
|
|
|
Use `argument-hint` in frontmatter to show expected arguments in autocomplete. Use `<angle brackets>` for required arguments and `[square brackets]` for optional ones:
|
|
|
|
```markdown
|
|
---
|
|
description: Review PRs from URLs with structured issue and code analysis
|
|
argument-hint: "<PR-URL>"
|
|
---
|
|
```
|
|
|
|
This renders in the autocomplete dropdown as:
|
|
|
|
```
|
|
→ pr <PR-URL> — Review PRs from URLs with structured issue and code analysis
|
|
is <issue> — Analyze GitHub issues (bugs or feature requests)
|
|
wr [instructions] — Finish the current task end-to-end
|
|
cl — Audit changelog entries before release
|
|
```
|
|
|
|
## Usage
|
|
|
|
Type `/` followed by the template name in the editor. Autocomplete shows available templates with descriptions.
|
|
|
|
```
|
|
/review # Expands review.md
|
|
/component Button # Expands with argument
|
|
/component Button "click handler" # Multiple arguments
|
|
```
|
|
|
|
## Arguments
|
|
|
|
Templates support positional arguments and simple slicing:
|
|
|
|
- `$1`, `$2`, ... positional args
|
|
- `$@` or `$ARGUMENTS` for all args joined
|
|
- `${@:N}` for args from the Nth position (1-indexed)
|
|
- `${@:N:L}` for `L` args starting at N
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
---
|
|
description: Create a component
|
|
---
|
|
Create a React component named $1 with features: $@
|
|
```
|
|
|
|
Usage: `/component Button "onClick handler" "disabled support"`
|
|
|
|
## Loading Rules
|
|
|
|
- Template discovery in `prompts/` is non-recursive.
|
|
- If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest.
|