第 章 技能

认识 Skills

痛点：想让 agent 学会新能力。却只能改源码，维护成本高。

工具长在 agent 的代码里加一个就得改源码。

但很多想让 agent 学会的能力其实是知识——发版流程、commit 规范、内部 CLI 用法。

Anthropic 的 Agent Skills 就是为这种知识能力准备的：把一项能力写成一个文件夹。丢进约定目录，agent 就学会了不改一行代码。

Claude Code 率先落地。规范开放在，很快成了跨工具标准，pi 实现的也是这一套。不过，

示例结构：

demo-skills/
release/
SKILL.md ← "怎么发版"的说明书
bump-version.sh ← 说明书里引用的脚本
commit-style.md ← "commit 规范"。简单到一个文件就够

加载效果：

$ npx tsx ch07/skills.ts
== 加载到的技能 ==
- commit-style: 按团队规范写 commit message。说起来，当使用者要求提交代码或写 commit 时使用。- release: 给本项目发版。当使用者说"发版""发布新版本""bump version"时使用。

Skill 目录结构详解

release/
├── SKILL.md ← 必需文件，包含 frontmatter 与正文
├── bump-version.sh ← 可选资源

• ① 目录：skill 的分发单位。拷贝、git、发布成包，都能直接使用。
• ②a frontmatter：

  字段	作用	约束
  Name	skill 唯一标识，也是手动触发时的命令名（/skill:release)。默认使用目录名兜底，	小写字母/数字/连字符，≤ 30 字符。
  Description	模型判断“什么时候该用”该 skill 的唯一依据。必须包含触发词，	必填，≤ 200 字符。

  其他实现可以自行 字段），但 Name + Description 是跨工具最小共识。
• ③ 资源文件：脚本、模板等。正文里用相对方法引用（./bump-version.sh)，解析基于 skill 所在目录。
• • 目录式的观点是，SOME_SKILL/SKILL.md + 资源文件们
  • 单文件式这方面，仅有正文且无资源。可直接用 SOME_SKILL.md

从零写加载器

Pain point：*把所有 skill 全部塞进 system prompt* → 每次请求都带几万 token，成本爆炸，模型注意力被噪声淹没。

A. 初版思路

// 简单粗暴版：把每个 skill 全文拼进 system prompt
let skillSection = "
# Skills
";for ) {
skillSection += "
---
" + readFileSync;}
systemPrompt += skillSection;

- 两个 skill 时还能接受；如果积累到数十甚至上百个，每个 ~800 字。则约 .5 万 token 常驻程序提示**，费用和都被占满**。

B. Progressive Disclosure

The key insight: **frontmatter = 商品标签，正文 = 说明书 **。只把标签放进 prompt，正文留在磁盘。需要时模型自行 #read.

第一版 vs progressive disclosure 对比 ┌───────────────────── system prompt ──────────────────────┐ │…│← 常驻、计费、噪声 └───────────────────────────────────────────────────────────────┘ progressive disclosure: │ name + description + location │← 几千 token 清单 │ 使用者："帮我发个版" → description 命中 → read│← 按需加载正文 └───────────────────────────────────────────────────────────────┘

C. 实现步骤

1. 解析 Frontmatter

export function parseFrontmatter: { fm: Record;body: string } {
const m = raw.match
---
/);if return { fm: {},body: raw };const fm: Record = {};for ) {
const i = line.indexOf;老实说，if fm = line.slice.trim;说起来，}
return { fm,body: raw.slice };}

2. 扫描目录并收集 MiniSkill

export interface MiniSkill {
再看name，string;description: string;filePath: string;按理说，// 正文所在方法。用于 read
baseDir: string;// 相对方法解析根目录
}
export function loadSkills: MiniSkill {
if ) return;const out: MiniSkill =;for ) {
const sub = join;const file = existsSync)
join // 目录式
: name.endsWith?按理说，sub : null;其实，// 单文件式
if continue;const {fm}=parseFrontmatter);怎么说呢，if continue;// 必须有 description
out.push({
再看name，fm.name?，name.replace,description: fm.description。filePath:file,baseDir: dirname,});}
return out;不过，}

3. T​oken‑友好渲染清单

export function formatSkillsForPrompt:string{
if return "";const items = skills.map(s=>
`
`+
` ${s.name}
`+
` ${s.description}
`+
` ${s.filePath}
`+
``
).join;return `
The following skills provide specialized instructions for specific tasks.
Use read tool to load a skill's file when task matches its description.

${items}
`;}

4. D​emo 输出

commit-style
按团队规范写 commit message。当使用者要求提交代码或写 commit 时使用。其实，
/path/to/demo-skills/commit-style.md


release
给本项目发版。当使用者说"发版""发布新版本""bump version"时使用。
/path/to/demo-skills/release/SKILL.md

D. 调用流程

① system prompt 包含清单 ② 使用者："帮我发个版" ③ 模型匹配 description → 决定使用 *release* ④ 模型调用 read → 正文进入上下文 ⑤ 按说明执行后续步骤

说到*关键点*。没有任何新机制，只是复用第 章的 #read.

细节提醒

• X​ML 标签防止与对话混淆；模型把它当结构化数据读取。
• P​rompt 中加入 “When a skill file references a relative path。resolve it against skill directory” 指示，以确保相对方法基于 skill 本身而非当前 cwd。
• S​kill 必须配合已有的 #read;没有此工具则不渲染清单，以免产生空洞。

skill 脚本谁来执行？

Pain point：*担心每个 Skill 都需要额外的运行时环境* → 不需要！

The spec’s smartest “non‑action”: **脚本直接走已有的 #bash.** 说明书里写 “跑 . /bump-version.sh patch"”。模型按照记录好的 basesDir​` 拼绝对方法，接下来调用普通 bash 工具。整个执行链仍然是：

1. #read → 获得 SKILL.md 正文；
2. #bash → 执行相对方法指向的脚本；
3. #edit/#bash 等其它工具继续完成任务。

Demos – 完整运行记录

$ npx tsx ch07/loop.ts "帮我给这个项目发个 patch 版"
read
---
description: 给本项目发版…---
...
好的，按 skill 流程来：跑 bump 脚本升 patch...
bash
至于bash。.../bump-version.sh: Permission denied
bash
bump patch
edit…更新 package.json …Successfully replaced block
bash
> demo@... test
all tests passed
✅ 完成！
patch 版本已从 0.1.0→0.1.1，测试全绿。tag 已跳过，

*要点回顾*

5. No extra runtime – just reuse existing tools.
6. Bash 是唯一收口。所以沙箱策略只需要拦截 Bash，即可统一保护 Skill 脚本与其他命令。
7. If script lacks executable flag,model can自行修复 .
8. Description 决定何时触发；正文则提供具体步骤与可选脚本。

脚本沙箱设计概览

加载器的边界情况

Pain point:*脏数据导致 loader 崩溃或误加载* –
• *缺少 description*：直接跳过不加载。
• *单文件 Skill 未显式 Name*：父目录名兜底导致冲突——强制要求单文件必须提供 Name 字段。说起来，
• *重名冲突*的观点是，先到先得。全局 skills 在前、项目 skills 在后全局优先覆盖项目同名技能。
• *不该扫进去的方法*：跳过 dotfiles、node_modules、遵循 .gitignore；怎么说呢，遇到 SKILL.md 时停止递归。不再向下搜索子 Skill。<\/ul>\ <\/ul>

  手动触发

  If you want deterministic control instead of letting model guess,expose a slash command.

  // 将 /skill:name 转换为完整 Skill 正文注入当前轮次
  export function expandSkillCommand:string{
  if ) return text;const space=text.indexOf;其实，const name=space===-1?text.slice:text.slice;const args=space===-1?"":text.slice.trim;const skill=skills.find;ifreturn text;const {body}=parseFrontmatter);const block=`
  References are relative to ${skill.baseDir}.
  ${body.trim}
  `;return args，说起来，`${block}
  ${args}` : block;}
  <\/c ode>

  E.g.,输入:

  /skill:release
  这次发个 patch 

  输出注入块的观点是。

  
  References are relative to /path/to/demo-skills/release.…，不过，
  这次发个 patch 

  • 规则同步注入块里声明 “References are relative to …按理说，”，对应清单中的方法解释。让模型始终按 baseDir 拼接相对方法。
  • 禁用模型自动调用在 frontmatter 加上 disable-model-invocation:true c ode>。loader 在渲染清单时过滤掉该技能，仅保留手动 /skill: 调用入口。按理说，适用于高危或仅供管理员使用的 runbook。
  <\/ul>

  怎么写好一个 Skill

  • Description 必须“做什么 + 当何时用”。精准触发词 能明显提高召回率。至于例如，给本项目发版。当使用者说“发版”“发布新版本”“bump version”时使用。按理说， c ode>.

• {Single‑file vs Directory} - 单文件：纯文字且无资源 → 必须显式提供 Name；避免撞名，- Directory：包含脚本、模板或正文超过一屏 → 推荐采用目录结构，自带干净 baseDir。不过，

<\/li>

• {Runbook 风格正文} 编号步骤 ✅。明确成功判定 ❌,把每条命令原样放置，可直接 copy‑paste。让模型像阅读操作手册一样顺畅执行。<\/li>
• {内部资源拆分} 长表格或 API 文档放到独立文件。例如 ./fields.md c ode>,正文中引用即可，实现二层 progressive disclosure。<\/li>
• {常见反模式检查}
  • No trigger phrase – 导致永远不被召回。
  • Packing whole wiki – 超长且缺描述，会占满 token 并降低召回准确度。不过，
  • Scrip t without exec flag 且未指明 bash 前缀 – 会报 Permission denied。需要作者自行处理或在说明中补充 #bash ./script.sh c ode>`。<\/ul>

对照 pi 的工业级实现

关键问题与答案
a) 拦截层级？	Bash 为唯一入口；说起来，所有 Skill 脚本、使用者自定义命令、模型生成命令均走此口子。只在 Bash 前做一次 sandbox 即可覆盖全部执行场景。.
b) 隔离机制？		Linux 使用 bubblewrap、macOS 使用 sandbox‑exec；pi 封装为 @anthropic-ai/sandbox-runtime，实现统一接口。.
b) 替换后端？		通过 pi 的 #user_bash 钩子，在开启沙箱时返回自定义操作对象；未开启时保持默认 spawn。.
d) 策略配置？老实说，		配置文件 .pi/sandbox.json { "network": {"allowedDomains":}。"filesystem": { "denyRead":,"allowWrite":,"denyWrite": } } 默认拒绝，一切未列入白名单的网络请求均被阻断；文件程序同理，只允许项目根和 /tmp 写入。.
结果：无论 Skill 自带何种脚本。都在同一套沙箱下执行，无需在 loader 中额外编写任何配合代码。老实说，.

 – collision 策略 “先到先得”+diagnostic detectCollisions，全局优先于项目  – formatSkillsForPrompt XML 清单 /core/skills.ts 中同名函数，支持 disable-model-invocation 等 字段  – expandSkillCommand 注入块 /core/session.ts::_expandSkillCommand，支持非交互模式自动展开  – 

	额外特性
parseFrontmatter	utils/frontmatter.ts	–
loadSkills	loadSkillsFromDir、 respecting .gitignore 与 symlink	–
description 必填过滤	loadSkillFromFile 中校验并记录 warning	–
Name 格式校验	validateName 并输出 diagnostic
三来源合并 loadGlobalSkills,loadProjectSkills。loadExplicitSkills  –

<\/tbody>

<\/table>

踩过的坑与产出

li>全文常驻 Prompt 成为每次请求都交税——progressive disclosure 是规模化前提。li>/description 必填，否则模型无法匹配。li>/single‑file Skill 必须显式 Name，否则父目录兜底导致所有此类技能同名冲突。其实，li>/重名冲突采用“全局优先”。因为全局 skills 在项目 skills 前加载。li>/方法 A 完全依赖 #read 工具；若环境缺失则不应渲染清单，以免产生不可达入口。li>/相对方法必须基于 Skill 所在目录，所以 both 清单指示语 与 注入块 均需声明此规则。li>/Skill 脚本走 Bash，无独立运行时 ⇒ 沙箱只需要拦截 Bash。即可统一保护所有外部命令，包括未知第三方 script。li>/disable-model-invocation 字段仅影响方法 A。使其从清单消失，仅保留手动 /skill: 调用渠道。li>/发现 SKILL.md 后停止递归 ⇒ 禁止在一个 Skill 文件夹内部再嵌套另一个 Skill，以免漏检。<\/ol>

至于**产出**，

li>彻底理解 Agent Skills 标准：目录＝分发单位、frontmatter＝常驻商品标签、正文＝按需加载说明书、资源按 baseDir 相对解析。li>完整可运行的 mini 加载器 ：frontmatter解析 → 扫描 → XML 清单渲染 → /skill: 注入。按理说，一次命令即可离线跑通。不过，li>Token账务计算明确——Progressive Disclosure 把常驻 token 从数万降至千余。实现大规模技能库可行性，li>沙箱设计思路：“Bash 为唯一收口”，利用 OS 层面隔离。无需为 Skills 编写额外配合代码，实现“一行也不改”。li>实际经验集合，包括常见异常处理、常用方法还有反模式检查。为你快速建立可靠、安全且易维护的 Coding Agent 技能程序奠定基础。