← Pi Agents

技能

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)也会被发现,所以一个列出所有技能的测试会把它包含在内。