指令四层 —— 从 AGENTS.md 到 SKILL.md
前三章都在配「Pi 能做什么」。这一章配的是「Pi 怎么想」。
大多数人只会用一个地方:往 AGENTS.md 里堆规则。堆到两百行之后发现
——模型开始忽略后半段,而且每次请求都白白付着这两百行的 token。
Pi 给了四层不同代价的入口,选对层比写得好更重要。
三个问题:
- 我在子目录里放一个
AGENTS.md,它会覆盖根目录那个吗? SYSTEM.md和APPEND_SYSTEM.md差一个字,行为差多远?- 一个技能有两百行说明,怎么才能只在用到时才付出这部分 token?
第 1 层 SYSTEM.md 整段替换系统提示词 最贵,也最横 第 2 层 APPEND_SYSTEM.md 追加到系统提示词 与上一层不合并,二选一 第 3 层 AGENTS.md 作为「项目指令」注入 按目录链叠加,不覆盖 第 4 层 SKILL.md 只注入名字和描述 用到才读全文 ─────── F04 的四层,代价从上到下递减 ─────── 另有 prompts/*.md 不是注入,是你手动敲 /name 才展开一、探索链:AGENTS.md 从哪几个目录找
loadContextFileFromDir(resource-loader.ts:212-231)定义了同目录下的优先级,
就是一个长度 5 的候选名数组(:213),按顺序试,命中即返回:
| 顺序 | 文件名 |
|---|---|
| 1 | AGENTS.override.md |
| 2 | AGENTS.md |
| 3 | AGENTS.MD |
| 4 | CLAUDE.md |
| 5 | CLAUDE.MD |
同一个目录里只取第一个存在的,五个名字是同义词,不是累加。
AGENTS.MD 和 CLAUDE.MD 那两个全大写版本是给文件系统大小写敏感的
场景准备的(macOS 上 Agents.md 和 AGENTS.md 是两个文件)。
跨目录的部分在 loadProjectContextFiles(:260-302)。它分两段走:
先放全局,再放祖先链。 第一步读 <agent-dir> 里那个
(:270-274),第二步从 cwd 一路往上走到根,
每层找到一个就 unshift 进数组(:290)。
unshift 这个词是关键:从当前目录往上走,越往上越靠前插入,
所以最终顺序是全局 → 最外层祖先 → … → 当前目录。
近的在后,也就是近的更靠后、更容易被模型重视。
配置文档的说法是「a context file applies whenever Pi runs in its directory
or anywhere below it」(configuration.md:43)——它们是叠加关系。
三件事顺带说明白:
子目录的 AGENTS.md 不会覆盖父目录的。 两份都进提示词,
按从外到内的顺序排列。
同目录 AGENTS.override.md 优先。 这不是 URL 覆盖,
是「二选一」的覆盖——configuration.md:45 原文是
replaces AGENTS.md or CLAUDE.md only in the same directory。
它不需要项目信任。 F01 已经说过,这里再说一遍原因:
loadProjectContextFiles 根本不接收 isProjectTrusted(),
它是 Pi 启动流程里少数无条件读的路径(configuration.md:47)。
1.1 git worktree 的那个特例
:242-258 有一个函数叫 findShadowedContextFile,专门处理
git worktree add 造出来的嵌套工作树。逻辑是:如果当前目录是个
嵌套 worktree,且它自己也有 AGENTS.md,那么主仓库那份就跳过。
为什么?注释写得很直接:两者「occupy the same logical repository scope」, 两份都加载等于把同一段上下文应用两次。这是个很细的坑, 你在用 worktree 时会遇到「为什么规则被说了两遍」——答案在这。
二、SYSTEM.md 与 APPEND_SYSTEM.md:二选一,不合并
这两个文件的发现逻辑几乎一模一样(:1245-1271),
都是先看项目、再看全局,命中即返回:
<!-- file: pi-main/pi-main/packages/coding-agent/src/core/resource-loader.ts -->
private discoverSystemPromptFile(): string | undefined { const projectPath = join(this.cwd, CONFIG_DIR_NAME, "SYSTEM.md"); if (this.settingsManager.isProjectTrusted() && existsSync(projectPath)) { return projectPath; }注意两个 return:项目那份命中就返回了,全局那份根本不会被读。
这就是 configuration.md:39 那句「Files with the same name are not combined」
的代码实现。
所以行为矩阵是这样:
SYSTEM.md 在哪 |
结果 |
|---|---|
项目 .pi/ 有(且已信任) |
用项目的,全局那份被忽略 |
项目没有,全局 <agent-dir>/ 有 |
用全局的 |
| 都没有 | 用 system-prompt.ts 里拼出来的默认提示词 |
注意项目那份受信任闸门约束(isProjectTrusted() 在条件里),
而 AGENTS.md 不受。这是四层里唯一有这个区别的地方。
2.1 替换 vs 追加,代价差多少
SYSTEM.md 是整段替换。换了之后,Pi 那套
preamble / tools / rules / docs / cwd 五段结构还在不在?
取决于你怎么写。buildSystemPromptSections(system-prompt.ts:128-160)
里 customPrompt 只顶掉 preamble 这一段(:152-153):
<!-- file: pi-main/pi-main/packages/coding-agent/src/core/system-prompt.ts -->
if (customPrompt) { promptSections.preamble = customPrompt; } else {也就是说 SYSTEM.md 换的是开头那段身份描述,工具清单、规则、
文档路径这些结构化段落仍然由 Pi 现算。这个设计很克制:
你写自己的开场白,但不会因此丢掉「有哪些工具」这种必须准确的信息。
APPEND_SYSTEM.md 则是往末尾追加,不动任何既有段落。
它的用途基本只有一个:跨项目通用的偏好,比如「回答用中文」
「不要给我写总结章节」。这类东西写进全局 APPEND_SYSTEM.md,
每个项目都生效,又不影响任何人自己的 AGENTS.md。
一句话选型:改「Pi 是谁」用 SYSTEM.md,加「我的习惯」用 APPEND_SYSTEM.md,
写「这个项目的规矩」用 AGENTS.md。
三、AGENTS.md 里到底该写什么
这一层是「项目上下文」,注入形式是一个 XML 块,
由 renderProjectContext(system-prompt.ts:79-86)生成:
Project-specific instructions and guidelines:<project_instructions path="D:\proj\AGENTS.md">(文件原文)</project_instructions>带 path 属性很重要——模型能看出某条规则来自哪个目录,
在多层叠加时这个信息不可省。
因为是原文注入,写得越啰嗦,每个 turn 就多付一次。 三条经验,都是踩出来的:
写「怎么验证」,不写「要注意质量」。 后者模型本来就知道,
前者是它猜不到的。比如「跑 npm run all,它会依次做八件事」
比「提交前请充分测试」有用一百倍。
写「不要做什么」,且给出替代。 「不要用 npm run build,
用 npm run build:fast」是可执行的;「构建时小心」不是。
路径写相对路径。 注入块里没有 cwd 信息,模型的当前目录在另一段
(sections.cwd)。绝对路径会让人在 clone 到别处之后全部失效。
想验证注入效果,还是那招——看 sections.docs:
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonlt.jsonl 里 message_end 那条 system 消息的 sections.docs
就是所有上下文文件拼起来的那一段。文件里写了什么,这里就该看到什么
——如果没看到,是没找到文件,不是模型没读。
四、SKILL.md:只注入名字,用到才展开
前三层的代价都是「每 turn 全量」。技能解决的是「有一大套流程, 但一个月才用一次」。
formatSkillsForPrompt(skills.ts:358-388)只做一件事:
把每个技能的名字、描述、位置三行塞进一个 <available_skills> 块。
正文一个字都不进提示词。每个技能固定输出三个字段(:377-383):
// skills.ts:379-381<name>${escapeXml(skill.name)}</name><description>${escapeXml(skill.description)}</description><location>${escapeXml(skill.filePath)}</location>location 是个绝对路径。模型判断「这个任务匹配」之后,
会用 read 去读那个文件,读完才拥有完整指令。
这就是渐进加载:先付一条描述的钱,需要时再付全文的钱。
4.1 一个技能的最小形态
目录 + SKILL.md:
pdf-tools/├── SKILL.md├── scripts/extract.sh└── references/formats.md---name: pdf-toolsdescription: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.---# PDF toolsRead `references/formats.md` before converting a document.Run scripts relative to this skill directory.description 是唯一决定「会不会被想起来」的字段。skills.md:37
的要求是:既说清做什么,也说清什么时候用。
「Helps with PDFs」这种描述路由不到任何具体任务。
name 有格式约束:小写字母、数字、连字符,不能以连字符开头或结尾,
不能连续两个连字符,最长 64 字符;描述最长 1024
(skills.md:81)。不合规只是警告,不会阻止加载
(skills.md:7,skills.ts:313-332 也是记 warning 后继续)。
4.2 强制加载与隐藏
模型可能漏掉一个明明相关的技能。skills.md:45 给的解法是手动敲:
/skill:pdf-tools extract report.pdf后面那串参数会作为「用户请求」追加到技能正文后面
(skills.md:47-51)。
反过来的需求也有:某个技能只想被人手动调用,不想被模型自动联想。
在 frontmatter 里加一行 disable-model-invocation: true,
它就从 <available_skills> 里消失了(skills.ts:359 那个 filter),
但 /skill:name 还能用。
4.3 放哪儿
按 skills.md:57-63,Pi 认这几个位置:
| 位置 | 范围 |
|---|---|
<agent-dir>/skills/ |
全局 |
.pi/skills/ |
项目(需信任) |
~/.agents/skills/ |
Agent Skills 标准的全局位置 |
.agents/skills/ |
标准位置,从 cwd 向上找到仓库根 |
技能目录是递归扫描的(skills.md:59)——这和扩展只下一层正好相反。
所以你可以在 skills/ 下面按分类建子目录,skills/pdf/tools/SKILL.md
照样能被找到。
最后一条安全提醒来自原文(skills.md:65):技能可以让模型跑脚本、改文件。
信任一个项目之前,先看看它的 .pi/skills/ 里有什么。
五、prompts/:不是注入,是手敲的快捷方式
这一层和上面四层性质不同——它不进系统提示词。
<agent-dir>/prompts/*.md 里的每个文件变成一个斜杠命令,
你敲 /文件名 时才展开成一段话发给模型。
占位符替换在 substituteArgs(prompt-templates.ts:76-108),
支持这些写法:
| 写法 | 含义 |
|---|---|
$1 $2 … |
第 N 个参数 |
$@ 或 $ARGUMENTS |
所有参数拼起来的整串 |
${1:-默认值} |
第 1 个参数,缺省用默认值 |
${@:-默认值} |
全部参数,缺省用默认值 |
${@:2} |
从第 2 个开始到末尾 |
${@:2:3} |
从第 2 个开始取 3 个 |
两个容易踩的点:
不递归替换。 注释写得很明确(:73-75):只替换模板字符串本身,
参数值和默认值里出现的 $1 不会再被展开。所以你没法用默认值套默认值。
序号从 1 开始,但 ${@:0} 不报错。 :89-91 有个 if (start < 0) start = 0,
把 0 当 1 处理——bash 习惯。写错成 ${@:0} 不会给你任何提示。
文件不合法时会发生什么?prompt-templates.ts:110-115 之后是
解析 frontmatter 的逻辑,出错记 warning 并跳过该文件,
其余提示词照常可用。和技能一样:单点失败不拖垮全局。
六、自己动手验证
实验 1:看叠加顺序。
在项目根建 AGENTS.md 写 ROOT-MARK,在 src/ 建 AGENTS.md 写 SRC-MARK,
然后 cd src 跑:
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonl用 F03 那个 tools.mjs 改个字段名,把 sections.tools 换成 sections.docs
打出来。期望:ROOT-MARK 在前,SRC-MARK 在后。
再把根目录的改成 AGENTS.override.md,重跑——ROOT-MARK 还在,
但文件名变了,因为 override 只是同目录内的替换。
实验 2:确认 AGENTS.md 不受信任影响。
进一个没信任过的仓库(.pi/ 里有 settings.json 但内容随意),
跑 pi -p "x" -na(--no-approve 强制不信任)。
此时 .pi/settings.json 被忽略,但 AGENTS.md 仍然出现在 sections.docs 里。
这是本章最值得亲手确认的一条——它和「项目配置」是两套机制。
实验 3:确认技能只注入了三行。
在 <agent-dir>/skills/demo/SKILL.md 写一个 200 行的技能,
描述写 Use when testing skill loading。跑起来看 sections.docs,
搜索 available_skills:你只会看到 <name> <description> <location>
三行,正文那 200 行不在里面。
改一处试试
给全局 APPEND_SYSTEM.md 加一行:
Always answer in Chinese, even if the code and comments are in English.然后随便跑一次。这条规则每个项目都生效,而你不用改任何人的
AGENTS.md。反过来,如果你想试试 SYSTEM.md,写一句话进去,
用 sections.preamble 观察——只有那一段变了,
sections.tools 和 sections.rules 原封不动。
七、工程暗坑
坑一:以为子目录的 AGENTS.md 会覆盖父目录。
它是叠加。想「只让子目录生效」,得让父目录那份自己消失,
没有「取消继承」的开关。
坑二:项目 SYSTEM.md 与全局 SYSTEM.md 不合并。
「不合并」的意思是全局那份完全不被读,不是「项目覆盖同名键」。
把公共部分放全局、项目只写差异,这个用法在 SYSTEM.md 上不成立。
坑三:AGENTS.md 越写越长,每 turn 都付钱。
两百行上下文文件对每个 turn 都是固定成本。长流程搬到 SKILL.md
里,用不到就不花钱。
坑四:技能不写 description 就等于不存在。
skills.ts:306-308 和 :330-332 两处都在检查:没有描述,
非显式声明的技能直接不加载。而且不报错。
坑五:提示词模板里的 $ 会被吃掉。
想在提示词里写一个字面的 $1 给模型看,做不到——它一定会被替换。
要么改措辞,要么把这个符号拆到参数里传进去。
八、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/coding-agent/src/core/resource-loader.ts |
1,320 | 五个候选名、祖先链 unshift、两个 discover* |
packages/coding-agent/src/core/system-prompt.ts |
229 | renderProjectContext、五段结构与 customPrompt |
packages/coding-agent/src/core/skills.ts |
506 | frontmatter 校验、formatSkillsForPrompt 三行注入 |
packages/coding-agent/src/core/prompt-templates.ts |
326 | substituteArgs 七种占位符 |
packages/coding-agent/docs/configuration.md |
47 | 13 项 / 8 项 / 上下文文件三节 |
packages/coding-agent/docs/skills.md |
93 | 技能的目录形态与 frontmatter 字段 |
九、下一章
四层指令都是「静态文本」。F05 开始写代码:扩展到底怎么被加载、
on() 那四十多个钩子里哪些真正常用、
以及怎么在工具真正执行之前把它拦下来。