通过描述通告一个技能,按需加载正文
写出一个 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.