pstack 架构拆解
H02 / 十层

一个目录,一份 SKILL.md
这就是全部载体

pstack 用的是 Agent Skills 这套格式:技能就是一个文件夹,文件夹里必须有一份 SKILL.md,文件开头用 --- 包住一小段元数据。没有构建、没有注册表、没有 SDK。 上游 50 份技能加起来 2,247 行——比一个中型源文件还小。

图 2-1一个技能目录的解剖(真实文件)

用 why 当样本,因为三种附件它都有:正文、references、更深的 sources。左边是磁盘上的样子,右边是运行时看到的顺序。

ON DISK 磁盘 pstack/skills/why/ SKILL.md 158 行 · 唯一必需 · 全站最长 references/ epistemics.md investigator-prompt.md source-playbook.md synthesizer-prompt.md sources/ 再下一层 · 8 份证据源 SKILL.md 内部 --- name: why description: Use for "why does X... disable-model-invocation: true ↑ 装载器只读这一段 · 第三个键关掉自动触发 ## 正文(写给 agent 的说明书) 步骤、判据、模型默认值 链接指向 references/, agent 需要时才顺着链接再读 IN CONTEXT 上下文 第一步:只有 description 50 条一行摘要常驻 第二步:命中才读正文 SKILL.md 158 行进入 第三步:顺着链接取附件 investigator-prompt.md… 目录里可能出现的四种东西(上游实测计数) SKILL.md 50 / 50 —— 必需,正文 references/ 9 / 50 —— 可选,共 30 份附件 scripts/ 2 / 50 —— 可选,真代码 playbooks/ 仅 poteto-mode 有 —— 23 份剧本(H05) 附件不受规范强制,纯靠正文里的相对链接被发现
图 2-1 · 关键设计:frontmatter 是索引,正文是手册,附件是附录。三层分开,才装得下 50 个技能。

图 2-2体积分布:绝大多数技能很短

这是 pstack 最重要的手感:技能不是长文。50 份 SKILL.md 的中位数是 31 行,最短 7 行,最长 158 行。24 条原则平均只有 22 行。

每个桶里的技能个数 · n=50 最短 7 行 · 中位数 31 行 · p90 106 行 · 最长 158 行 8 ≤ 20 行 24 21 – 40 7 41 – 70 9 71 – 120 2 > 120 读法:32 份文件(64%)在 40 行以内。超过 120 行的只有 2 份(why 158 行、poteto-mode 147 行),且都把长材料挪进了 references/。
图 2-2 · 数据来自上游仓库 wc -l skills/*/SKILL.md(提交 e43c7ee),核对日期 2026-10-05。

2-3这种载体的三个代价

纯文字不是免费的。pstack 换来可移植性,付了三笔账:

代价 1
靠模型自觉
没有类型检查、没有单测。poteto-mode 里那句"必须点名原则",本质是一句请求,不是强制。
代价 2
会撞名字
Cursor 自带一个 babysit 技能,触发词和 pstack 的 Babysit 剧本一模一样。根文件必须专门写一句"用剧本、别用宿主那个"。
代价 3
要外置状态
文字记不住"上次跑到哪"。所以才有 H10 那层:orch.ts、decisions.tsv、/tmp/<slug>-resume.md。
本层的检验问题:为什么 50 个技能能同时"装"在机器上却不撑爆上下文? 答案在 frontmatter 只暴露 name + description 这一件事上——这正是下一层 H03 的主题。
上一站← H01 问题与定位