技能
Pi 按名称和描述通告每一个技能,并按需加载它的完整指令;这里讲的是如何写出让路由(routing)生效的描述。
第 12 章的 /review 只在你键入它的时候运行。它所解决的那个问题有一个兄弟:有些工作应当在 Pi 辨认出任务的种类那一刻就开始,而不需要你先说出命令的名字。
那就是技能(skill),而整个机制都转折在一个你会想要匆匆跳过的字段上。
技能实际上是什么
skills.md 开篇给出定义:技能为某一种特定的工作给 Pi 提供专门的指令和支撑文件。Pi 按名称和描述通告每一个可用的技能,然后只在任务需要时才加载它的完整指令。
加载那一侧说的是同一件事:启动时,Pi 扫描已配置的技能位置,并把每个技能的名称、描述和路径加进系统提示词。它不加完整指令。
flowchart TD
A["启动"] --> B["系统提示词携带名称、描述、路径"]
B --> C{"任务匹配吗"}
C -->|否| D["其他什么都不加载"]
C -->|是| E["模型读取 SKILL.md"]
F["你键入 /skill:name"] --> E
E --> G["正文指令进入上下文"]
G --> H["打包的文件,如果正文这么说"]
两个属性随之而来。描述始终存在于请求中;正文不是。这就是为什么一个技能在无关时几乎不花任何代价,以及为什么描述就是整个路由面。
错误:"任务需要时 Pi 就运行一个技能。"
正确:"Pi 通告的是描述。模型把它与任务匹配,只有在那之后才读取正文。"
这个目录
review-guard/
├── SKILL.md
├── scripts/
│ └── run-checks.sh
├── references/
│ └── checklist.md
└── assets/
└── review-template.md
一个技能是一个包含 SKILL.md 的目录。Pi 实现了 Agent Skills specification,大多数无效字段产生的是警告,而不是中止启动。
SKILL.md
---
name: review-guard
description: 评审变更后的代码是否符合本仓库的约定,并运行它自己的检查。在评审 diff、拉取请求或未提交变更时使用。
---
# 评审守卫
1. 运行 `scripts/run-checks.sh`,在评审任何东西之前先读它的输出。
2. 读 `references/checklist.md`,并把它应用到 diff 上。
3. 按严重程度排序报告发现的问题,每一条都附上文件路径。
不要把 diff 总结给用户;只报告发现的问题。
frontmatter 后面跟着直接的指令。这就是整个文件格式。
描述就是路由机制
skills.md 异乎寻常地明确:
描述决定模型何时考虑加载这个技能。既要说明这个技能做什么,也要说明它何时适用。避免使用诸如"帮助处理 PDF"这样的描述,它们没有提供足够的路由信息。
比较同一个技能的三种描述:
description: 帮助处理评审。 # 做什么:含糊;何时:从不
description: 评审代码。 # 做什么:是;何时:从不
description: 评审变更后的代码是否符合本仓库的约定。评审 diff、拉取请求或未提交变更时使用。 # 两者都有
只有第三种给了模型某种可以把任务匹配上去的东西。“评审代码"可能会合理地匹配上一个实现任务;而"评审变更后的代码……评审 diff、拉取请求或未提交变更时使用"不会。
这也是第 11 章那套流程把技能排在模板之上的原因。经得起推敲的措辞是:描述是文本,但它是通过一种路由约定交付的文本——模型收到它,并决定是否加载正文。这是一个真实的机制,它与 /review 不一样,后者运行是因为你请求了。要说"路由是模型施加于一条描述的约定”,而不要说"路由是文本不可能拥有的能力";后者是一个绝对化的断言,而描述本身就是正在做路由的文本。
描述有时会失手
skills.md 说一个模型可能加载不了一个相关的技能,并给出了覆盖方式:
/skill:review-guard
/skill:name 之后的参数会作为一条用户请求追加到已加载的指令后面:
/skill:review-guard src/auth only
所以两条路径都到达上面图里同一个方框:技能的正文,被加载并被遵循。如果你在例行公事地键入 /skill:name,那描述需要改进——或者这个技能其实是一个模板。
退出自动选择
当一个技能只应通过它的显式命令可用时,在 frontmatter 里设置 disable-model-invocation: true。enableSkillCommands 设置(默认 true)控制技能命令是否出现在交互式命令发现中;手动键入的 /skill:name 命令仍然有效。
这给了你三种值得刻意选择的状态:
| 状态 | Frontmatter / 设置 | 能到达模型吗? |
|---|---|---|
| 被路由且被列出 | 默认 | 能,通过描述匹配 |
| 被路由但对菜单隐藏 | enableSkillCommands: false |
能 |
| 仅显式可用 | disable-model-invocation: true |
不能 |
可移植的 frontmatter
这份规范定义了这些字段:
| 字段 | 用途 |
|---|---|
name |
命令与显示名称 |
description |
展示给模型的路由描述 |
license |
许可证名称或随包分发的许可证文件 |
compatibility |
环境要求 |
metadata |
附加的键值元数据 |
allowed-tools |
实验性的预先批准工具列表 |
disable-model-invocation |
把技能从自动的模型选择中隐藏 |
名称使用小写字母、数字和连字符,不能有前导、尾随或连续的连字符,最多 64 个字符;描述最多 1024 个。
有两个有文档记载的行为需要知道。当声明的名称与父目录不一致时,Pi 既不要求也不警告,但其他 Agent Skills 实现可能会强制执行这一点,所以名称保持一致仍然是可移植的选择。而格式错误的 SKILL.md 文件,加上没有描述的已声明技能,根本不会被加载——缺少描述是一次静默的消失,不是一个错误。
名称冲突会保留第一个被发现的技能并产生一条警告。如果两个技能都声称叫"review",发现顺序决定你得到哪一个。
技能从哪里加载
把技能放进你的用户或项目技能目录。包含 SKILL.md 的目录会被递归发现,所以在这里嵌套没有问题——不像提示词模板只加载直接的 .md 子项。
Pi 也支持 Agent Skills 的位置 ~/.agents/skills/ 和 .agents/skills/。项目的 .agents/skills/ 目录会从工作目录开始向上经过它的各级祖先被发现,当存在仓库根目录时在那里停下。
Pi 接受一些独立的 Markdown 技能,但包含 SKILL.md 的目录是可移植的形式,应当优先采用。
迭代改进
从一个技能可被发现的位置运行 Pi,然后检查启动诊断信息和 /skill:name 命令。在活动会话中编辑过技能之后运行 /reload。
启动时打印的头部列出了 Pi 加载的指令和资源,你就在那里确认描述确实进去了。
这个一贯示例:/review 长成一个技能
第 11 章说过,发布清单是那个超出了模板容量的案例。这里是更小的那个版本,评审守卫,处于技能规模:
---
name: review-guard
description: 评审变更后的代码是否符合本仓库的约定,并运行它自己的检查。在评审 diff、拉取请求或未提交变更时使用。
---
# 评审守卫
1. 运行 `scripts/run-checks.sh`,在评审之前先读它的输出。
2. 读 `references/checklist.md`。
3. 按严重程度排序报告发现的问题,每一条都附上文件路径。
与模板同样的工作,而每一个差异都来自它是一个技能这件事:它不靠键入就会触发,并且它的指令只在相关时才加载。
第二个是一个约束,而不是一项好处。正文在技能每次触发时都会整体加载,所以清单一旦装不进一屏,它就不能住在那里。第 14 章把它移到正文旁边的目录里。
运行了什么
examples/ch13-skills/ 在用户技能目录里创建技能,并检查 provider 收到的系统提示词:
- 提示词携带每个技能的名称、描述和路径,而不携带它的正文:一个放在正文里的标记字符串从未出现过;
- 一个没有
description的技能不会被通告; /skill:name把正文作为请求加载,参数追加在后面;disable-model-invocation: true把技能从被告知给模型的内容里移除,但让/skill:name仍然有效;- 技能会被递归发现,不像提示词模板;
- 两个同名的技能中,恰好只有一个被通告。
写你自己的测试时需要知道一件事:运行测试那台机器上的一个技能(~/.agents/skills)也会被发现,所以一个列出所有技能的测试会把它包含在内。