加载规则与实战模板

argument-hint：让补全告诉你该输什么

官方给了 argument-hint 这个字段，用来在自动补全里显示期望的参数。它在 frontmatter 里声明，用于必填参数；可选参数用方括号 [...] 包起来：

---
description: Review PRs from URLs with structured issue and code analysis
argument-hint: "<url>"
---

文档里渲染出来大概长这样（示意）：

→ pr — Review PRs from URLs ...
  wr [instructions] — Finish the current task end-to-end
  cl — Audit changelog entries before release

对我们的 mdcheck：

---
description: 用 md-tools 检查 markdown 文件的质量
argument-hint: "<file.md>"
---
用 md-tools 检查 markdown 文件：$1

这样输入 /mdcheck 后，补全会提示 file.md，不会让人一脸懵。

---

加载规则：prompts 不递归

官方文档明确了一条重要规则：

prompts/ 目录里的模板发现是「非递归」的。

也就是说，放在 prompts/ 里的模板，只有直接子文件会被发现。子目录里的不会自动扫到。

如果你想把模板放进子目录（比如按功能分组），就得显式加进 prompts 设置或包清单里，而不是指望它自动发现。

---

模板从哪来：问 Pi 帮你建

文档开头就说：「pi can create prompt templates. Ask it to build one for your workflow.」 你甚至可以不用手写，直接让 Pi 帮你生成。

比如你可以对它说：

给 md-tools 建一个提示词模板 /mdcheck，用 $1 接受文件名，
默认检查 README.md，要求用 stats 统计并指出格式问题。

这正好体现 Pi 的设计哲学——很多定制工作本身就能由 Pi 自己完成。你描述需求，它写模板。

---

一个完整的 md-tools 模板包

把三节学的串起来，你可以建三个配套模板：

# mdcheck.md —— 检查质量
---
description: 用 md-tools 检查 markdown 文件质量
argument-hint: "<file.md>"
---
用 md-tools 检查 $1，用 stats 统计并指出格式问题。

# mdconvert.md —— 转纯文本
---
description: 用 md-tools 把 markdown 转成纯文本
argument-hint: "<file.md>"
---
用 md-tools 的 convert 命令把 $1 转为纯文本并展示。

# mdrename.md —— 安全改名
---
description: 用 md-tools 预览并确认改名
argument-hint: "<file.md> <新名.md>"
---
用 md-tools 的 rename 命令把 $1 改为 $2，先预览，确认后才执行。

注意第三个把「先预览再执行」也写进了模板——安全规则跟着模板走。

---

落地练习：打磨你的 md-tools 模板

1. 为三个模板都加上 argument-hint，让补全提示清晰
2. 验证 prompts/ 非递归规则：把 mdcheck.md 移进子目录，确认它不再被发现
3. 尝试直接对 Pi 说「帮我建一个模板」，让它生成一个再对比你手写的差异

怎么判断做对了？——补全能提示期望参数；子目录里的模板确实不出现；Pi 生成的模板也能正常用。

卡住了怎么办？ 子目录模板消失 → 这是非递归的正常表现，需显式加进设置。补全不提示 → 检查 argument-hint 拼写和位置。想让 Pi 建 → 描述清楚文件名、参数、正文要求。

---

常见坑：子目录放了一堆模板却一个都扫不到

新手常见的困惑：明明 prompts/子目录/ 里放了好几个模板，调用时却一个都没有。这不是 bug，是「非递归」规则。 官方明确 prompts/ 只发现直接子文件。

解决：要么全放 prompts/ 根目录，要么把子目录模板显式写进 prompts 设置。理解了这条，模板目录就不会「神秘失踪」。

---

小结

1. argument-hint 让补全提示期望参数，必填用 <>、可选用 []
2. prompts/ 的模板发现是非递归的
3. 子目录模板要显式加进设置或包清单
4. 可以直接让 Pi 帮你建模板
5. 安全规则（如先预览再执行）可以写进模板正文

下一节进入 M04——扩展开发，这是 Pi 最强大的定制能力。