Example

通过描述通告一个技能,按需加载正文

写出一个 SKILL.md,确认系统提示词携带它的名称、描述和路径但不携带正文,并用 /skill:name 强制加载它。

一个提示词模板要等到你键入它。一个技能在 Pi 辨认出任务的种类时开始。整个机制都转折在一个字段上:系统提示词携带每一个技能的名称、描述和路径,从不携带正文,所以描述就是整个路由面。本页写出一个 SKILL.md,并精确展示模型被告知了什么。

写出这个技能

一个技能是一个包含 SKILL.md 的目录:

review-guard/
└── SKILL.md
---
name: review-guard
description: 评审变更后的代码是否符合本仓库的约定,并运行它自己的检查。在评审 diff、拉取请求或未提交变更时使用。
---

# 评审守卫

1. 运行 `scripts/run-checks.sh`,在评审任何东西之前先读它的输出。
2. 读 `references/checklist.md`,并把它应用到 diff 上。
3. 按严重程度排序报告发现的问题,每一条都附上文件路径。

把它放进你的用户或项目技能目录,并从一个它可被发现的位置运行 Pi。描述既要说明这个技能做什么,也要说明它何时适用;“评审代码"没有给模型任何可以用来匹配"实现这个"的东西,而上面的文本给了它这样的东西。

模型被告知什么

启动时 任务匹配之后,或 /skill:name
名称、描述和路径,在系统提示词里 SKILL.md 的正文
不是正文 作为一条用户请求追加的参数

这个拆分就是为什么一个无关的技能几乎不花任何代价,以及为什么正文在每次触发时整体加载。一个已经长得超出一屏的正文,想要的是旁边有一个文件(第 14 章),而不是一个更长的 SKILL.md。

预期结果

作为支撑的测试在一个用户目录里创建技能,并检查 provider 收到的请求。它在 Pi 1.0.4 上断言:

  • 系统提示词匹配这个技能的名称、它的描述和 SKILL.md,而不匹配一个放在正文里的标记;
  • 一个没有 description 的技能完全不在提示词里——一次静默的消失,不是一个错误;
  • /skill:review-guard src/auth only 把正文和追加的参数放进用户消息;
  • disable-model-invocation: true 把描述从被告知给模型的内容里移除,但让 /skill:review-guard 仍然有效;
  • skills/group/inner/ 下的一个技能会被递归发现;
  • 两个都叫 review 的技能中,恰好只有一个被通告。

这些是来自一个带有脚本化 provider 的真实会话的已观察断言,不是一个真实模型决定路由的转录记录。

机制与局限

有文档记载: 被锁定的 docs/skills.md 定义了格式和 frontmatter 字段,说启动会把每个技能的名称、描述和路径加进系统提示词但不加完整指令,说明 /skill:name 之后的参数会被追加,记载了 disable-model-invocation,并指出包含 SKILL.md 的目录会被递归发现、没有描述的技能不会被加载。已观察: skills.test.ts 把上面的每一条都对照提示词和一个脚本化 provider 收到的消息做了检查。它从不亲自演练路由。

路由是一种约定,不是保证:docs/skills.md 说一个模型可能加载不了一个相关的技能,这正是 /skill:name 存在的原因。一个技能仍然是文本——它可以说"绝不强制推送”,但没有任何东西强制它。如果你例行公事地伸手去用 /skill:name,那描述需要改进,或者这个技能其实是一个模板。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.