做出第一个 Pi Skill
Skill 是一组按需加载的工作说明。Pi 启动时只把 Skill 的名称和描述放进上下文,任务匹配或你执行 /skill:<name> 时,才读取完整的 SKILL.md。
这份教程会创建一个只读的 release-check Skill。它检查发布准备情况,但不会打 tag、推送或发布。
什么时候应该写 Skill
先用最轻的机制:
| 需求 | 更合适的机制 |
|---|---|
| 每次会话都要遵守的约束 | AGENTS.md |
| 一段固定、手动展开的文本 | Prompt Template |
| 多步骤流程、脚本、参考资料 | Skill |
| 注册工具、监听事件或改变 TUI | Extension |
Skill 适合“怎么做”已经相对稳定,但不需要常驻上下文,也不需要直接扩展 Pi 运行时的任务。
第 1 步:创建目录
项目级 Skill 可以放在 .pi/skills/ 或 .agents/skills/。这里使用 Pi 专属位置:
mkdir -p .pi/skills/release-check项目级 Skill 只有在项目受信任后才会自动加载。第一次实验也可以通过 --skill 显式传入路径。
第 2 步:写 SKILL.md
创建 .pi/skills/release-check/SKILL.md:
---name: release-checkdescription: 检查代码库是否具备发布条件,输出阻塞项、警告和发布说明草稿。用于发布、打 tag 或部署之前的只读审查。---
# Release Check
## 安全边界
- 只读检查。不要修改文件。- 不要提交、推送、打 tag、发布包或部署。- 不要打印凭据或完整环境变量。
## 检查步骤
1. 运行 `git status --short`,确认工作树状态。2. 读取包清单、版本文件、changelog 和发布配置。3. 找出仓库声明的测试、类型检查和生产构建命令。4. 经用户允许后运行本地检查;跳过需要真实凭据或生产资源的命令。5. 比较最近版本,识别破坏性变更、迁移步骤和文档遗漏。
## 输出格式
按以下顺序输出:
1. `BLOCKERS`:发布前必须处理的问题。2. `WARNINGS`:需要人工判断的风险。3. `READY`:已经验证通过的项目。4. `UNVERIFIED`:因为环境或权限无法验证的项目。5. `RELEASE NOTES`:不超过 200 字的发布说明草稿。
每个结论附上文件位置或命令结果。没有证据时不要写“已通过”。前置元数据叫 frontmatter:
description必填,建议不超过 1024 个字符,同时写清“做什么”和“何时使用”;缺失或为空时 Skill 不加载。name建议显式填写并与目录名一致;Pi 缺省时使用父目录名。可移植名称使用小写字母、数字和连字符,最多 64 个字符,不能以连字符开头或结尾,也不能连续使用连字符。- Pi 对多数格式问题给出警告而不是直接阻止加载;其他 Agent 的校验规则可能更严格。
第 3 步:立即测试
不依赖自动发现,直接加载这个目录:
pi --skill .pi/skills/release-check进入 Pi 后执行:
/skill:release-check 检查当前仓库你应该看到 Pi 读取 Skill,并按 BLOCKERS、WARNINGS、READY、UNVERIFIED 和 RELEASE NOTES 输出结果。
如果当前项目已受信任,也可以正常启动 pi,再执行:
/reload/skill:release-check/reload 会重新加载 Skills、Extensions、Prompt Templates、主题、快捷键和上下文文件。
验证 Skill 是否真的生效
不要只看它是否出现在列表里。至少验证三条路径:
- 显式调用:
/skill:release-check能加载。 - 自然触发:输入“发布前帮我检查仓库,但不要发布”,Pi 能根据描述选择它。
- 安全边界:检查 Skill 是否按预期提醒发布风险;冲突指令和模型行为无法保证只读,真正禁止发布要靠权限与环境限制。
如果自然触发不稳定,先改 description。不要把大量触发关键词堆进正文,因为 Pi 在加载 Skill 前只看到元数据。
不希望模型自动选择某个 Skill 时,可在 frontmatter 中设置 disable-model-invocation: true;仍可用 /skill:<name> 显式调用。这只是选择方式,不是权限或安全开关。
让 Skill 保持小而准
推荐结构:
release-check/├── SKILL.md├── scripts/│ └── collect-release-facts.sh├── references/│ └── release-policy.md└── assets/ └── release-notes-template.md遵循渐进披露:
SKILL.md只保留决策、步骤和资源路由。- 长参考放进
references/,需要时再读取。 - 重复且确定的机械操作放进
scripts/。 - 输出骨架和示例文件放进
assets/。
所有相对链接都以 Skill 目录为基准:
发布规则见 [团队策略](references/release-policy.md)。选择项目级还是全局
| 位置 | 作用域 | 是否需要项目信任 |
|---|---|---|
~/.pi/agent/skills/ | 当前用户所有项目 | 否 |
~/.agents/skills/ | 多种 Agent Harness 共享 | 否 |
.pi/skills/ | 当前项目 | 是 |
.agents/skills/ | 当前项目,可与其他 Harness 共享 | 是 |
--skill <path> | 当前进程显式加载 | 否,显式路径仍会加载 |
.agents/skills/ 会从当前目录向上发现到 Git 仓库根目录。目录内需要递归找到 SKILL.md;根目录散放的 .md 文件会被忽略。
从其他 Harness 复用 Skills
Pi 可以在设置中加入其他工具的 Skill 目录:
{ "skills": [ "~/.claude/skills", "~/.codex/skills" ]}项目设置 .pi/settings.json 中的相对路径以设置文件所在目录为基准。例如:
{ "skills": ["../.claude/skills"]}共享不代表天然安全。Skill 可以要求模型运行脚本或执行高风险操作;使用前仍要审查正文、脚本、依赖和外部网络访问。
常见问题
Skill 没有出现
按顺序检查:
- 文件名是否为
SKILL.md,或是否位于.pi/skills/根目录的单个.md文件。 - frontmatter 是否包含非空的
description。 - 项目是否受信任。
- 是否执行过
/reload。 - 是否存在同名 Skill;冲突时 Pi 会警告并保留先发现的那个。
Skill 被加载了,但不按预期执行
- 把工作流约束放在步骤之前;需要强制的权限边界交给宿主环境。
- 每一步使用动作和证据,不写抽象愿望。
- 给出明确输出格式。
- 对破坏性动作使用“准备”和“确认”两阶段。
- 用真实仓库测试失败路径,而不只测试理想示例。
什么时候升级为 Package
当 Skill 需要在多个项目或团队中安装、固定版本或与 Extension、模板、主题一起分发时,再做成 Pi Package。
继续学习:
- 需要事件或自定义工具:做第一个 Extension。
- 需要现成任务模板:查看六个工程工作流。
- 完整格式与验证规则:Pi Skills 官方文档。