第 9 章 · Skills 技能体系
本章目标：理解技能（Skill）的渐进披露工作原理，掌握 SKILL.md 的结构与 frontmatter 字段，动手编写一个带脚本资源的可复用技能。
9.1 技能是什么：按需加载的能力包
技能是自包含的能力包：为特定任务提供专用工作流、安装说明、辅助脚本和参考文档。pi 实现了开放的 Agent Skills 标准（对标准的小偏差是宽容的，比如允许技能名与目录名不同）。
核心设计是渐进披露（progressive disclosure）：
启动时：扫描所有技能 → 只把「名称+描述」放进 system prompt
运行中：任务匹配某技能 → agent 用 read 工具加载完整 SKILL.md
执行时：按 SKILL.md 指令行事，用相对路径引用脚本/资源这样即使装了几十个技能，常驻上下文成本也只有几十行描述；完整指令只在真正需要时进入对话。
9.2 发现位置与安全前提
pi 从以下位置加载技能（--no-skills 可禁用发现，显式 --skill <path> 仍生效）：
全局: ~/.pi/agent/skills/ ~/.agents/skills/
项目: .pi/skills/ .agents/skills/（cwd 向上到 git 根）
↑ 项目位置仅在项目受信任后加载（见第 7 章）
包: skills/ 目录或 package.json 的 pi.skills 声明
设置: skills 数组显式指定文件或目录发现规则细节：~/.pi/agent/skills/ 与 .pi/skills/ 中根级散放的 .md 文件也会被识别为独立技能；但 ~/.agents/skills/ 和项目 .agents/skills/ 中根级 .md 被忽略——只有含 SKILL.md 的目录才算技能，且目录递归扫描。
先审查再使用
官方在文档中反复强调：技能可以指示模型执行任意操作，还可能携带模型会调用的可执行代码。安装社区技能前务必阅读其内容。
复用其他工具的技能只需加路径——Claude Code / Codex 的技能库直接兼容：
// ~/.pi/agent/settings.json
{
"skills": ["~/.claude/skills", "~/.codex/skills"]
}9.3 SKILL.md 结构与 frontmatter
一个技能就是一个含 SKILL.md 的目录，其余内容自由发挥：
pdf-tools/
├── SKILL.md # 必需：frontmatter + 使用说明
├── scripts/ # 辅助脚本
│ └── merge.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.jsonfrontmatter 字段（依据 Agent Skills 规范）：
| 字段 | 必需 | 说明 |
|---|---|---|
name | ✅ | ≤64 字符，小写字母/数字/连字符，不可连字符开头结尾或连续 |
description | ✅ | ≤1024 字符，决定 agent 何时加载它 |
license | — | 许可证 |
compatibility | — | 环境要求（≤500 字符） |
metadata | — | 任意键值对 |
allowed-tools | — | 预批准工具列表（实验性） |
disable-model-invocation | — | 设 true 则从 system prompt 隐藏，只能 /skill:name 手动调用 |
校验规则要记两条硬线：缺 description 的技能不加载；其余违规（名字超长、非法字符等）只警告不阻断。同名冲突时保留先发现的并警告。
description 是整个技能最关键的一行字——它就是"何时用我"的判断依据。对比官方给的示例：
# 好：具体、包含触发词
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
# 差：模糊，agent 无法判断适用时机
description: Helps with PDFs.9.4 实战：写一个 changelog-check 技能
下面是一个完整、可直接使用的技能：发布前检查 CHANGELOG 是否覆盖了本版变更。
mkdir -p ~/.pi/agent/skills/changelog-check/scripts<!-- ~/.pi/agent/skills/changelog-check/SKILL.md -->
---
name: changelog-check
description: 发布前检查 CHANGELOG.md 是否覆盖了自上一个 git tag 以来的全部重要变更。当用户准备发版或提到 changelog 时使用。
---
# Changelog Check
## 步骤
1. 找到上一个发布 tag：
```bash
git describe --tags --abbrev=0- 列出该 tag 之后的提交（
git log <tag>..HEAD --oneline）， 归类为 新增 / 变更 / 修复。 - 读取 CHANGELOG.md，检查每条已归类提交是否出现在未发布区块。
- 汇报：缺失条目以列表形式输出；全部覆盖则打印 "OK"。
规则
- 除非用户明确要求，不要修改 CHANGELOG.md。
- 忽略 merge 提交以及对用户无影响的
chore:提交。
Keep-a-Changelog 的格式细节见 references/format.md。
::: warning 关于示例的语言与格式
上面是**一个完整文件的原始内容**（所以没有教程式的小节编号）。技能正文是给模型读的自然语言指令，用中文或英文都可以——英文便于跨团队共享，团队内部使用时直接写中文完全没问题（模型两种语言都能理解）。`name` 字段例外：必须是小写字母/数字/连字符，不能用中文。
:::
使用方式有两种：
```bash
/skill:changelog-check # 手动强制加载执行
/skill:changelog-check v2.1 # 参数会以 User: <args> 追加到技能内容后
# 或者直接说"准备发版吧"，agent 匹配到描述后自动 read 加载正文结构是自由的
上面的 ## Steps、## Rules 只是给模型看的普通 markdown 约定——pi 只解析 frontmatter（name/description 等），正文怎么分节完全由你决定（官方示例惯用 ## Setup/## Usage）。真正被“执行”的是模型读到的自然语言指令。
要点回顾：正文里引用资源必须用相对技能目录的路径（如上例的 references/format.md）；enableSkillCommands 设置（默认开启）控制是否注册 /skill:name 命令。
9.5 从社区获取技能
两个官方推荐的技能仓库：
- Anthropic Skills——docx/pdf/pptx/xlsx 文档处理、Web 开发；
- Pi Skills——网页搜索、浏览器自动化、Google API、转写。
克隆后把路径加进 settings 的 skills 数组即可（配合第 13 章的包机制还能做到版本化管理）。也可以直接让 pi 帮你写一个——官方文档原话是 "ask pi to build one for your use case"（让 pi 为你的用例现场写一个技能）。
本章小结
- 技能 = 含
SKILL.md的目录，渐进披露：平时只有 name+description 进上下文； - 项目技能目录（
.pi/skills/、.agents/skills/）受 Project Trust 门控； - frontmatter 硬规则：
name小写连字符 ≤64 字符，description缺失则不加载，其余违规仅警告； description写得具体与否直接决定自动触发的可靠性；- 正文用相对路径引用 scripts/references/assets；
/skill:name [args]手动触发。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. pi 技能的“渐进披露”是指什么？
2. 哪个技能会被 pi 直接拒绝加载？
3. 项目里的 .agents/skills/ 目录中的技能，什么时候可用？
4. SKILL.md 正文中想引用技能目录下的 references/api.md，正确的写法是？
🛠️ 动手实践
- 完整实现本章的 changelog-check 技能（补上
references/format.md），在一个有真实 tag 的仓库里验证。 - 把 Anthropic Skills 仓库克隆到本地并通过 settings 引入，测试其中一个文档处理技能。
- 给你的技能加上
disable-model-invocation: true，验证它从系统提示词消失、只能手动/skill:name调用。
完成练习后，进入下一章：Extensions 入门。