Example

给一个技能文件,以及一个它能运行的检查脚本

把参考资料和一个 POSIX shell 脚本打包在 SKILL.md 旁边;脚本必须大声失败,而一个打包的文件只在被读取时才到达上下文。

评审守卫的清单有四十项;把它内联进 SKILL.md 会在技能每次触发时把全部四十项都加载进来。改成把它打包成正文中点名的一个文件。一个打包的文件是磁盘上的一个文件——它只在模型用它自己的工具读它时才到达上下文。本示例中打包的脚本需要一个 POSIX shell,所以在 Windows 上要在 Git Bash 下运行它。

目录布局

review-guard/
├── SKILL.md
├── scripts/
│   └── run-checks.sh
└── references/
    └── checklist.md

SKILL.md 用相对于技能目录的路径点出这些文件,因为 Pi 会告诉模型技能住在哪里,好让它解析它们:

---
name: review-guard
description: 评审变更后的代码是否符合本仓库的约定,并运行它自己的检查。在评审 diff 时使用。
---

# 评审守卫

1. 运行 `scripts/run-checks.sh`,在评审任何东西之前先读它的输出。
2. 读 `references/checklist.md`。

这三个目录名是一种约定,不是强制的布局。要紧的是每一种何时加载:参考资料在技能判定任务相关之后被读,脚本在被要求时运行,资源在输出的那一刻被使用。

检查脚本

#!/usr/bin/env bash
# scripts/run-checks.sh - run the target repository's own verification.
set -euo pipefail

root="${PI_REVIEW_GUARD_ROOT:-$(git rev-parse --show-toplevel)}"
cd "$root"

echo "== repository: $root =="
echo "== typecheck =="
pnpm typecheck

这个脚本从不从它自己的路径推导仓库:dirname "$0" 是技能的 scripts/ 目录,而它与仓库之间隔了多少级父目录,取决于技能被安装在哪里。它向 Git 询问 Pi 被启动时所在工作目录的顶层,而这个目录是由 bash 工具继承的,不是技能的。set -euo pipefail 是一个失败的脚本和一个一边跳过一切一边以零退出的脚本之间的区别。

预期结果

作为支撑的测试在一个 POSIX shell 下运行这个脚本(没有可用的 POSIX shell 时跳过),PATH 上放一个替身的 pnpm,并为了上下文方面的论断驱动一个会话:

  • repo/.pi/skills/review-guard/scripts/ 下的一个项目技能在仓库根目录运行 pnpm——往上三级,所以数父目录会选错;
  • 仓库外的一个共享或打包的技能解析出同一个目标;
  • PI_REVIEW_GUARD_ROOT 覆盖发现过程;在 frontmatter 里点名这个变量没有效果,因为 Pi 里没有任何东西把 frontmatter 写进环境;
  • 脚本旁边一个打包的 guard.conf 会相对于脚本被找到;
  • 同一个失败行在有 set -euo pipefail 时以非零状态退出,没有它时以零状态退出,而没有它时脚本仍然打印了它的最后一行;
  • SKILL.md 的路径在提示词里,但 references/checklist.md 里的一个标记一直不存在,直到模型用它自己的 read 工具调用读了它。

机制与局限

有文档记载: docs/skills.md 说要使用相对于技能目录的路径、Pi 会告诉模型技能住在哪里,并把环境方面的准备保持在技能内部。已观察: skill-files.test.ts 执行这个脚本(需要 POSIX shell),并检查一个脚本化会话的提示词和工具结果。本书提出: 大小经验法则——正文放步骤,参考资料放决定之后才需要的细节,每次运行都需要的东西就内联。

git rev-parse 发现是一种约定,不是一道边界:一个被告知去运行脚本的模型拥有一条进入你这台机器的路径,而工作目录就是 Pi 被启动时所在的任何地方。frontmatter 不会变成环境变量。一个打包的文件不会神奇地出现在上下文里。在 Windows 上本示例需要 Git Bash;没有 POSIX shell 时测试会跳过。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.