Chapter 8 · Prompt Templates

Chapter goals: Master the存放位置, frontmatter format, parameterized syntax, and invocation方式 of pi prompt templates;学会组织团队共享 templates; and厘清 templates vs skills的分工边界.

8.1 What Templates Are: Reusable Markdown Prompts

A Prompt Template is a Markdown snippet file: type /filename to expand into a完整 prompt. It solves the "re-typing the same high-quality instruction反复" problem —固定流程的指令 like code review, commit message generation, weekly report汇总 are all suitable for做成 templates.

pi discovers templates from these locations (--no-prompt-templates可整体禁用):

~/.pi/agent/prompts/*.md      ← global personal templates
.pi/prompts/*.md              ← project templates (load only after the project is trusted)
package's prompts/ directory   ← distributed with the pi包
settings.json's prompts array ← explicitly指定 files or directories
CLI: --prompt-template <path> ←临时 load (可重复)

The discovery rule is non-recursive

Subdirectories under the prompts/ directory are not auto-scanned. To组织 templates in subdirectories; you must显式 list the paths in the settings' prompts array, or走 the package manifest declaration.

8.2 Frontmatter and Command Names

The filename (去掉 .md) is the command name: review.md → /review. Frontmatter supports three fields:

---
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

• description: optional; defaults to the正文第一个 non-empty line when missing;
• argument-hint: optional;提示 the parameter format in the autocomplete dropdown; <angle brackets> mean required; [square brackets] mean optional.

Autocomplete效果 (official example):

→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  wr   [instructions] — Finish the current task end-to-end

8.3 Parameterization: From Fixed Text to "Functional" Templates

Templates support a shell-like parameter syntax; this is what makes it更 powerful than a "pure text snippet":

---
description: Create a component
---
Create a React component named $1 with features: $@

/component Button                 # $1=Button, $@=Button
/component Button "click handler" # Multiple parameters分配 by position

Full parameter syntax一览:

Syntax	Meaning
$1, $2…	The Nth positional parameter
$@ / $ARGUMENTS	All parameters joined by spaces
${1:-default}	Use default when parameter 1 is missing
${@:-default}	Default值 when all parameters are missing
${@:N}	Start from the Nth parameter (1-indexed)
${@:N:L}	Take L parameters starting from N

组合示例 — a summary template with defaults:

---
description: Summarize session state
---
Summarize the current state in ${1:-7} bullet points.
Focus on ${2:-unfinished work}.

/summarize            # Equivalent to "in 7 bullet points; focus on unfinished work"
/summarize 3 blockers # 3 items; focus on blockers

8.4 Walkthrough: Building a Team Workflow Template Set

Below is a可直接落地的最小 template set; place in the project .pi/prompts/ to共享 with the repo:

<!-- .pi/prompts/cr.md -->
---
description: Structured code review for staged changes
---
Review the staged changes (`git diff --cached`) as a senior reviewer.

Output sections:
1. **Blockers** — must fix before merge (bugs, security, data loss)
2. **Should fix** — design/logic concerns with suggested alternatives
3. **Nits** — style and naming

Rules: cite file:line for every finding; no praise padding;
if the diff is empty; say so and stop.

<!-- .pi/prompts/commit.md -->
---
description: Generate a conventional commit from staged changes
---
Look at `git diff --cached` and write ONE commit message:

- Format: type(scope): imperative subject (<=72 chars)
- Body: what & why; not how; wrap at 100 chars
- Types allowed: feat fix refactor perf test docs chore

Print only the message in a fenced code block.

# Team members克隆 the repo and可直接使用:
/cr
/commit

进阶做法 for跨团队分发 is to put the templates into the pi包's prompts/ directory or the pi.prompts declaration in package.json; install via pi install (detailed in Chapter 13).

8.5 Templates vs Skills: Division of Labor Boundary

Both are "Markdown + optional resources"; but their定位不同:

Dimension	Prompt Template	Skill
Essence	An展开 of a fixed instruction	A能力包 (workflow + scripts + reference docs)
Trigger	Manual /name	/skill:name or the agent auto-loads when judging the task匹配
Context cost	一次性进入 the对话 after expanding	Progressive disclosure:平时只有描述占上下文
Typical scenario	Commit文案, review checklists, weekly reports	PDF处理, browser automation etc.复杂能力

经验法则: use a template for "a流程可一句话说完"; use a skill for需要配套脚本、参考文档 or on-demand loaded capabilities (展开 in the next chapter).

Chapter Summary

• Templates are Markdown files; the filenameis the command name; five locations: global/project/package/settings/CLI; discovery is non-recursive;
• Frontmatter三件套: description, argument-hint (<> required; [] optional); body;
• Parameter syntax支持 positional params $1, all $@, defaults ${1:-d}, and slicing ${@:N:L};
• Team sharing首选 the project .pi/prompts/ (distributed with git);规模化则打包;
• Template = fixed instructions; Skill = capability packs; choose by复杂度.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. A template file review.md placed under ~/.pi/agent/prompts/; how to调用 it in the editor?

2. What does ${1:-7} in a template表示?

3. Regarding the template directory discovery rule; which is correct?

4. Which of the following needs is更适合做成 a Skill rather than a Prompt Template?

🛠️ Hands-on Practice

1. Put this chapter's /cr and /commit templates into a真实 project's .pi/prompts/; run each once and调整 output格式 per your team's口味.
2. Write a /translate <language> template带 argument-hint;验证 the autocomplete dropdown's parameter提示.
3. Use the ${@:2} syntax to make a template where "the first parameter is a filename; the rest are all requirements";测试 parameter slicing是否符合预期.

After completing the exercises, proceed to Chapter 9: Skills System.