跳转到内容

做出第一个 Pi Skill

Skill 是一组按需加载的工作说明。Pi 启动时只把 Skill 的名称和描述放进上下文,任务匹配或你执行 /skill:<name> 时,才读取完整的 SKILL.md。

这份教程会创建一个只读的 release-check Skill。它检查发布准备情况,但不会打 tag、推送或发布。

什么时候应该写 Skill

先用最轻的机制:

需求更合适的机制
每次会话都要遵守的约束AGENTS.md
一段固定、手动展开的文本Prompt Template
多步骤流程、脚本、参考资料Skill
注册工具、监听事件或改变 TUIExtension

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:

  • 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 是否真的生效

不要只看它是否出现在列表里。至少验证三条路径:

  1. 显式调用:/skill:release-check 能加载。
  2. 自然触发:输入“发布前帮我检查仓库,但不要发布”,Pi 能根据描述选择它。
  3. 安全边界:检查 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 没有出现

按顺序检查:

  1. 文件名是否为 SKILL.md,或是否位于 .pi/skills/ 根目录的单个 .md 文件。
  2. frontmatter 是否包含非空的 description。
  3. 项目是否受信任。
  4. 是否执行过 /reload。
  5. 是否存在同名 Skill;冲突时 Pi 会警告并保留先发现的那个。

Skill 被加载了,但不按预期执行

  • 把工作流约束放在步骤之前;需要强制的权限边界交给宿主环境。
  • 每一步使用动作和证据,不写抽象愿望。
  • 给出明确输出格式。
  • 对破坏性动作使用“准备”和“确认”两阶段。
  • 用真实仓库测试失败路径,而不只测试理想示例。

什么时候升级为 Package

当 Skill 需要在多个项目或团队中安装、固定版本或与 Extension、模板、主题一起分发时,再做成 Pi Package。

继续学习: