提示词模板的位置与格式

提示词模板是什么

官方一句话定义：提示词模板是能展开成完整提示词的 Markdown 片段。 你在编辑器里输入 /名字 来调用它，名字 是文件名去掉 .md。

这跟技能的区别很关键：

	技能 Skill	提示词模板
本质	按需加载的能力包	展开成提示词的片段
触发	自动匹配或 /skill:name	输入 /模板名
有没有脚本	可以有	通常没有

一句话：模板是「帮你打字的」，技能是「教它怎么干活的」。我们两个都要用。

---

放哪：五种来源

官方列了提示词模板的加载来源：

来源	位置
全局	~/.pi/agent/prompts/*.md
项目（需信任）	.pi/prompts/*.md
包	包的 prompts/ 目录或 pi.prompts
设置	settings.json 的 prompts 数组
CLI	--prompt-template（可重复）

和技能一样，项目级 .pi/prompts/ 要等项目被信任后才加载。想全局用就放 ~/.pi/agent/prompts/。

---

长什么样：一个模板实例

官方给了一个最典型的模板，用来「审查暂存的 git 改动」：

---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps

拆开看：

• frontmatter 里可选 description，没有时用正文第一行
• 正文是展开后作为提示词的完整内容

对我们，一个 md-tools 的检查模板大概长这样：

---
description: 用 md-tools 检查一个 markdown 文件
---
用 md-tools 的 stats 命令检查 README.md 的质量：
- 统计字数、段落数、标题数
- 指出明显的格式问题
- 如有超长段落给出建议

---

文件名 = 命令名

最重要的规则：文件名就是命令名。 review.md 变成 /review。所以：

• ~/.pi/agent/prompts/mdstats.md → 调用 /mdstats
• .pi/prompts/convert.md → 调用 /convert

起一个好记、不冲突的名字，直接决定你顺不顺手。

---

落地练习：建你的第一个 md-tools 模板

1. 在 ~/.pi/agent/prompts/ 建 mdstats.md，写一个「检查 markdown 文件」的模板
2. 启动 pi，输入 /mdstats，确认它展开成完整提示词
3. 试一次带文件的调用（下一节细讲参数），确认模板能跑

怎么判断做对了？——输入 /mdstats 后补全能匹配、展开成你写的正文，Pi 照做。

卡住了怎么办？ 找不到模板 → 确认放在被扫描的目录、扩展名是 .md。项目级不生效 → 确认 .pi/prompts/ 已随项目被信任。想改描述 → 用 frontmatter 的 description，否则用正文第一行。

---

常见坑：把模板当技能用，装了一堆脚本

容易搞混的是：给提示词模板里塞脚本、塞复杂逻辑。模板就该是纯文本片段，复杂的执行逻辑应该做成技能或扩展。

判断标准很简单：模板里如果出现「要跑代码、要处理状态」，那就不该用模板，改用 Skill 或 Extension。模板干「输入展开」这一件事就好。

---

小结

1. 提示词模板 = 能展开成完整提示词的 Markdown 片段
2. 五种来源：全局、项目、包、设置、CLI
3. 文件名 = 命令名，x.md → /x
4. 项目级需信任，全局处处可用
5. 模板负责「输入展开」，复杂逻辑交给技能/扩展

下一节，给模板装上参数——$1、$@ 和默认值。