技能脚本和参考文件：用渐进式披露让 SKILL.md 保持精简

开始之前

你需要第 1 课的 reviewing-api-changes 文件夹，任何 SKILL.md 已经越写越长的技能也行。这一课的脚本是 Bash，会调用 git，所以有这两样的终端就够了。

示例技能和脚本是为这门课写的。规则来自 Agent Skills 规范和指南、Anthropic 的编写指南和 Claude Code 文档，见来源列表。

这里的每个事实都来自来源列表里的页面，阅读日期为 2026 年 11 月 4 日。本课不是实测。

把技能拆成四个部分

SKILL.md 写成了一本手册，是最常见的起点。Anthropic 的编写指南要你对每一段都问：模型需要它吗，它值不值这些 token。Agent Skills 指南把这变成一个检验：没有这条指令，智能体会做错吗？不会，就删掉。

下面是示例技能拆分之后的样子。步骤变短了，因为细节挪了出去，每个指针都写明了文件名和需要它的情形。

---
name: reviewing-api-changes
description: Reviews changes to an OpenAPI or Swagger spec for breaking changes such as removed fields, renamed paths and stricter validation. Use when the user asks whether an API change is safe to ship, compares two versions of an API, or edits a spec file, even if they never say "breaking change".
---

# Reviewing API changes

1. Run scripts/changed_specs.sh to list the spec files changed on this branch.
2. Read the old and the new version of each file.
3. If a change removes, renames or retypes a field, or tightens validation, read references/breaking-changes.md before you judge it.
4. Write the review with assets/review-template.md.

## Gotchas

- Specs under api/ are generated from the .yaml files. Review the .yaml source and skip the .json copies.
- A new required request field breaks existing clients, even though adding fields usually doesn't.

1. 删掉智能体本来就知道的内容。指南举的例子是一段解释 PDF 是什么的文字：要用哪个库可以留着，解释删掉。
2. 只有部分任务才用得到的材料，挪进 references/。这里的 breaking-changes.md 就是会让客户端出问题的变更清单。一个文件讲一个主题，因为文件越小，加载时占的上下文越少，超过 100 行的文件开头加一个目录。
3. 必须每次结果一致的工作，挪进 scripts/。找出改动过的规范文件就属于这一类，所以它变成了 changed_specs.sh。
4. 输出模板和固定数据放进 assets/。审查模板只在智能体写审查报告时才加载。
5. 在 SKILL.md 里指向每个文件，并写明什么时候打开。指南举的好例子是“如果 API 返回非 200 状态码，就读 references/api-errors.md”，不好的是含糊的“详见 references/”。
6. 每个文件都直接从 SKILL.md 链接出去。一个参考文件再指向第二个文件时，Claude 可能只用 head -100 预览第二个，漏掉后面的内容。
7. 路径写成相对技能文件夹的形式，一律用正斜杠，Windows 上也一样。在 Claude Code 里，${CLAUDE_SKILL_DIR}/scripts/changed_specs.sh 不管技能装在哪里都能解析到。

什么放哪里，各占多少上下文

智能体分三个阶段加载技能。先是名称和描述，每个技能都有。任务匹配之后，加载 SKILL.md 正文。技能文件夹里的其他文件最后才加载，而且只有某个步骤伸手去拿的时候。概览页给出了结论：一个技能可以带几十个参考文件，任务只需要一个，就只读一个。

脚本走的路更省。智能体运行 changed_specs.sh 时，脚本代码不会进入上下文，进入的只是脚本打印出来的内容。所以 Anthropic 更推荐一个测试过的脚本，而不是让智能体当场现写代码，那样每次运行都要花 token 和时间。

reviewing-api-changes/
├── SKILL.md
├── references/
│   └── breaking-changes.md
├── scripts/
│   └── changed_specs.sh
└── assets/
    └── review-template.md

写智能体能运行的脚本

在 SKILL.md 里写明，脚本是用来运行的，还是用来阅读的。Anthropic 的指南拿两句话做对比：“Run analyze_form.py to extract fields”，和“See analyze_form.py for the extraction algorithm”。通常选运行，因为它比重新生成的代码更可靠。Agent Skills 指南还给了一个什么时候该打包脚本的信号。智能体每次运行都在重新发明同一个小工具，比如画图或解析某种格式，就把它写一次、测好，放进 scripts/。

一次性的命令根本不需要脚本。有现成的软件包能干这件事，脚本指南说就在指令里用固定版本直接调用，比如 npx eslint@9 --fix . 或 uvx ruff@0.8.0 check .，并写明前提条件，比如 Node.js 的版本。

下面这个示例脚本照着指南里给智能体运行的代码的规则来写：从不弹提示，用 --help 打印用法，分支不存在时指出怎么改，每行输出一个路径。

#!/usr/bin/env bash
# List OpenAPI or Swagger files changed against a base branch, one path per line.
set -euo pipefail

if [ "${1:-}" = "--help" ]; then
  echo "Usage: scripts/changed_specs.sh [BASE_BRANCH]"
  echo "Prints one changed OpenAPI or Swagger file per line. BASE_BRANCH defaults to main."
  exit 0
fi

base="${1:-main}"
if ! git rev-parse --verify --quiet "$base" > /dev/null; then
  echo "Error: branch '$base' was not found. Pass the branch to compare against, for example: scripts/changed_specs.sh origin/main" >&2
  exit 2
fi

git diff --name-only "$base"...HEAD | grep -Ei '(openapi|swagger).*\.(ya?ml|json)$' || true

• 不要交互提示。智能体在非交互的 shell 里工作，等待输入的脚本会卡死。输入通过参数、环境变量或标准输入传入。
• 一段简短的 --help，智能体就是靠它了解脚本的用法。它的输出会进入上下文窗口，所以要简短。
• 错误信息要说清哪里出了错、期望的是什么、该怎么试。一句含糊的“输入无效”只会白白浪费一轮。
• 数据走标准输出，诊断信息走标准错误，格式用 JSON、CSV 或 TSV 这样的结构化形式。
• 允许安全重试。智能体可能把一条命令跑两遍，所以“不存在就创建”比“创建，重复了就报错”好。

Anthropic 的 Barry Zhang 和 Lydia Hallie 怎么用技能文件夹

Anthropic 的研究工程师 Barry Zhang，2025 年 10 月在 X 上回复说，Skills 源自他做的一个原型，那个原型是为了证明 Claude Code 是一个通用智能体。团队由此得出结论：技能有 bash 和文件系统就够了。这正是本课的布局：参考资料是智能体用 bash 读的文件，脚本是它用同样方式运行的程序。

在 Anthropic 做 Claude Code 的 Lydia Hallie，2026 年 3 月发了一条技巧，讲需要实时数据的技能。在 Claude Code 里，SKILL.md 中由感叹号加反引号命令组成的一行，会在技能被调用时运行，命令的输出替换掉这一行，模型只看到结果。放到示例技能里，这一行可以在智能体读第 1 步之前，就把改动过的规范文件列表交给它。

X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。X 在第一条帖子处用“Show more”截断了后面的内容。点击截图可到 X 上打开原帖。

常见错误

• 指针没有条件。“详见 references/”让智能体只能猜，那个文件可能永远不会被打开。
• 引用链：SKILL.md 链接到 advanced.md，它又链接到 details.md。每个文件都应该离 SKILL.md 只有一层。
• 把智能体必须遵守的规则埋在参考文件里。Agent Skills 指南把注意事项留在 SKILL.md 里，因为智能体可能认不出什么情形该去翻另一个文件。
• 给一堆工具让它选。指定一个默认的，再提一个备选，比如文字提取用 pdfplumber，只有扫描件才用 pytesseract。
• 脚本假定所需的软件包已经装好。要在 SKILL.md 里列出来。Claude API 的沙箱不能在运行时安装软件包，需要软件包的脚本在那里会失败。

自己试一试

打开一个你写的 SKILL.md，用 wc -l SKILL.md 数一数行数。找出一段只有部分任务才用得到的内容，挪进 references/ 下的一个文件，换成一个写明打开哪个文件、什么时候打开的指针。再把第 1 课的那几条提示跑一遍。

然后找一个智能体每次都用同一种方式做的步骤，比如列文件或校验输出。它要好几条命令才能完成的话，就把它写成脚本，并加上 --help 说明。

• 文件夹里的每个文件，是否都从 SKILL.md 链接出去，并写了打开它的理由？
• 脚本跑两遍会不会造成损害？
• SKILL.md 正文是否远低于上面数字里的上限？

下一课

这样拆好的技能读起来轻松，加载起来也便宜。它管不管用，是另一个问题。第 3 课用提示、重复运行，以及不带技能的对照组，来测试触发情况和输出质量。

技能的初稿、文件夹规则和头信息限制，都在 Mindket 讲怎样创建 Agent Skill 的文章里。做好的技能文件夹在 Mindket 上以套件的形式上架。对项目里每个任务都成立的指令，不属于某一件具体的事，该写进 CLAUDE.md，Claude Code 每次会话开始都会加载它。

常见问题

资料来源

1. Agent Skills specification (2026年11月4日 查阅)https://agentskills.io/specification
2. Agent Skills: Best practices for skill creators (2026年11月4日 查阅)https://agentskills.io/skill-creation/best-practices
3. Agent Skills: Using scripts in skills (2026年11月4日 查阅)https://agentskills.io/skill-creation/using-scripts
4. Claude Platform docs: Skill authoring best practices (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
5. Claude Platform docs: Agent Skills (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
6. Claude Code docs: Skills (2026年11月4日 查阅)https://code.claude.com/docs/en/skills
7. Barry Zhang on X: where Skills came from, 16 October 2025 (2026年11月5日 查阅)https://x.com/barry_zyj/status/1978951690452615413
8. Lydia Hallie on X: inject shell output into a skill, 18 March 2026 (2026年11月5日 查阅)https://x.com/lydiahallie/status/2034337963820327017