做出第一个 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-check
description: 检查代码库是否具备发布条件，输出阻塞项、警告和发布说明草稿。用于发布、打 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。name 和 description 是必填项：
name使用小写字母、数字和连字符，最多 64 个字符。description最多 1024 个字符，要同时写清“做什么”和“何时使用”。- 缺少
description的 Skill 不会加载。
第 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 保持小而准
推荐结构：
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 官方文档。