Skills：让 pi 学会新技能

pi 有一个非常巧妙的设计：渐进式披露（Progressive Disclosure）。Skills 的技能描述常驻在系统提示词中，但完整的操作指令只在需要时才加载。平时不占上下文空间，用的时候才”翻开手册”。

你可以把 Skill 理解成 pi 的”专业培训手册”——平时放在架子上，任务匹配时自动取下来翻看。

本章基于 pi v0.84.1，pi 实现了 Agent Skills 标准。

---

Skill 是什么

一个 Skill 就是一个包含 SKILL.md 文件的目录。SKILL.md 里写了这个技能的名称、描述、以及详细的操作指令。pi 在工作时如果发现当前任务匹配某个 Skill 的描述，就会自动用 read 工具加载完整的 SKILL.md，然后按其指令执行。

从功能上看，Skill 和 Extension（扩展）都能给 pi 增加能力。但它们的定位完全不同：

维度	Skill	Extension
形式	Markdown 文件 + 可选的脚本/资源	TypeScript/JavaScript 代码包
能力边界	指导 pi 如何使用已有工具完成特定任务	注册新的 tool、hook、provider
复杂度	纯文本，无需编程	需要写代码
适用场景	”怎么用现有工具做某件事”的操作手册	”pi 本身没有但你需要”的新工具
举例	PDF 处理流程、API 调用指南	自定义 GitHub tool、新 provider

简单来说：Skill 教 pi 怎么做事，Extension 给 pi 新的工具。

---

Skill 的工作原理

pi 启动时做三件事：

1. 扫描所有 Skill 位置，提取每个 Skill 的 name 和 description
2. 把所有 Skill 的描述以 XML 格式嵌入系统提示词中
3. 当用户任务匹配某个 Skill 的描述时，AI 自动用 read 加载完整的 SKILL.md

这套设计的精髓在于：只有 description（最多 1024 字符）始终在上下文中，完整的操作指令按需加载。几十个 Skill 放在那就占几百字符的描述，但如果每个都提前加载完整指令，上下文窗口早就不够用了。

---

Skill 放在哪

pi 从以下位置加载 Skill：

位置	作用范围	发现规则
~/.pi/agent/skills/	全局	根目录 .md 文件 + 含 SKILL.md 的目录，递归发现
~/.agents/skills/	全局	仅含 SKILL.md 的目录，递归发现；根目录 .md 被忽略
.pi/skills/	项目	根目录 .md 文件 + 含 SKILL.md 的目录，递归发现（项目信任后生效）
.agents/skills/	项目	仅含 SKILL.md 的目录，递归发现
Pi Packages 的 skills/ 目录	全局或项目	随 package 分发

也可以通过 settings.json 手动指定：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills",
    "../.claude/skills"
  ]
}

这样一来，你在 Claude Code 或 OpenAI Codex 里用的 Skill 可以直接复用，不需要重新安装。

启动时加 --no-skills 可以禁用自动发现，但通过 --skill <path> 显式指定的 Skill 仍然会加载。

---

SKILL.md 的格式

一个 Skill 本质上就是一个带 Frontmatter 的 Markdown 文件。目录结构非常自由：

my-skill/
├── SKILL.md              # 必需：Frontmatter + 操作指令
├── scripts/              # 辅助脚本（可选）
│   └── process.sh
├── references/           # 详细参考文档（按需加载）
│   └── api-reference.md
└── assets/               # 模板、配置等静态资源
    └── template.json

Frontmatter 字段

SKILL.md 以 YAML Frontmatter 开头，定义元信息：

字段	必填	说明
name	是	技能名称，最多 64 字符。仅小写字母、数字、连字符
description	是	技能说明，最多 1024 字符。AI 根据它判断是否加载该技能
license	否	许可证名称
compatibility	否	环境要求说明，最多 500 字符
metadata	否	自定义键值对
allowed-tools	否	预批准的工具列表（实验性功能）
disable-model-invocation	否	设为 true 时，Skill 不自动出现在系统提示词中，只能手动调用

名称规则：

• 1~64 字符
• 只能用小写字母、数字、连字符（-）
• 不能以连字符开头或结尾
• 不能有连续的连字符

合法的：pdf-processing、data-analysis、code-review 不合法的：PDF-Processing、-pdf、pdf--processing

pi 不强制要求 name 与父目录名一致——标准虽这么规定，但 pi 认为共享 Skill 目录时这个限制不合理。

内容正文

Frontmatter 之后就是 Markdown 格式的操作指令。里面可以包含代码块、链接、表格等任何 Markdown 元素。

引用 Skill 目录中的文件时，用相对路径：

详见 [参考指南](references/REFERENCE.md)

运行脚本：
```bash
./scripts/process.sh <input>
```text

---

怎么写一个好的 description

description 是 Skill 的灵魂。AI 根据它判断”这个任务该不该加载那个 Skill”。下面是对比：

差——太模糊：

description: 处理 PDF 文件。

AI 不知道什么时候该加载，任何跟文件操作沾边的任务都可能触发。

好——具体明确：

description: 从 PDF 文件提取文字和表格、填写 PDF 表单、合并多个 PDF。在需要操作、读取或生成 PDF 文档时使用。

AI 能准确判断：用户说的是”合并两个 PDF”→ 加载；用户说的是”把 Word 转成 PDF”→ 不加载。

---

Skill 命令：手动调用

每个 Skill 自动注册为 /skill:名称 命令：

/skill:brave-search
/skill:pdf-tools extract

命令后的参数会以 User: 参数 的形式追加到 Skill 内容中。

有时候你不想让某个 Skill 自动被触发——比如它是一个危险操作或者很费钱的 API 调用。这时可以在 Frontmatter 中设置 disable-model-invocation: true，这样 Skill 不会出现在系统提示词里，只能通过 /skill:名称 手动调用。

也可以通过 settings.json 彻底关闭所有 Skill 命令：

{
  "enableSkillCommands": false
}

---

一个完整的自定义 Skill 示例

假设你需要 pi 帮忙管理项目的 CHANGELOG。每次发版前，你希望 pi 根据 git 提交历史生成标准化的变更日志。

目录结构

changelog-generator/
├── SKILL.md
└── references/
    └── keepachangelog-spec.md

SKILL.md

---
name: changelog-generator
description: 根据 git 提交历史自动生成符合 Keep a Changelog 规范的 CHANGELOG 条目。在准备发版、更新版本日志、或需要梳理项目变更时使用。
---

# Changelog Generator

根据最近的 git 提交历史生成标准化的 CHANGELOG 条目。

## 工作流程

1. 运行 `git log` 获取自上一版本以来的所有提交
2. 将提交按类型分组：
   - `Added`：feat 类型的提交（新功能）
   - `Changed`：refactor、perf 类型的提交（变更和优化）
   - `Deprecated`：标记为废弃的功能
   - `Removed`：删除的功能
   - `Fixed`：fix 类型的提交（Bug 修复）
   - `Security`：安全相关的修复
3. 为每组生成一个条目列表
4. 输出格式参照 CHANGELOG 规范（详见 [规范参考](references/keepachangelog-spec.md)）

## 版本号处理

- 先检查当前的 `package.json` 或 `version` 文件获取版本号
- 如果没有版本文件，询问用户当前版本号

## 输出格式

输出 Markdown 格式的 CHANGELOG，可直接粘贴到 `CHANGELOG.md`。

## 注意事项

- 合并提交（merge commit）不纳入变更条目
- 如果某个提交同时属于多个类型，归入最主要的类型
- 提交信息里的 Jira/issue 编号保留在条目中

使用

把这个目录放到 ~/.pi/agent/skills/changelog-generator/ 下，重启 pi。之后当你说”帮我生成这次的 CHANGELOG”时，pi 会自动加载这个 Skill 并按照 SKILL.md 中的流程执行。

你说”看看这周改了什么”时 pi 可能不加载——因为 description 里写的是”准备发版、更新版本日志”，而不是”查看变更”。

---

Skill 的校验规则

pi 启动时会校验每个 Skill，大部分问题只产生警告而非阻止加载：

• name 超过 64 字符或包含非法字符 → 警告
• name 以连字符开头/结尾或有连续连字符 → 警告
• description 超过 1024 字符 → 警告
• description 缺失 → 不加载
• 名称冲突（不同位置有同名的 Skill）→ 保留先发现的，警告

未知的 Frontmatter 字段会被忽略，不会报错。

---

官方 Skill 仓库

不想自己写？可以直接用社区维护的 Skill：

• Anthropic Skills：文档处理（docx、pdf、pptx、xlsx）、网页开发等
• Pi Skills：网页搜索、浏览器自动化、Google API、音频转录等

---

小结

Skill 是 pi 生态中最轻量的扩展方式。不需要写代码，一份 Markdown 文件就能教会 pi 新本事。它的渐进式披露设计保证了上下文的高效利用——几十个 Skill 常驻，但只有当前任务需要的那个才会加载完整的手册。

和 AGENTS.md（定规矩）与提示词模板（固化常用操作）配合，你已经有了三个层次的定制手段：规矩 → 流程 → 能力。