Agent Skills 参考

Agent Skills ↗ 是一种开放格式，用于向 agent 提供专业知识和可重复的工作流。skill 是包含 SKILL.md 文件的文件夹。该文件包含名称、描述和一种任务的说明。文件夹还可以包含 script、参考文档、template 和其他文件。

Agent Skills 已作为开放标准发布。许多 agent 支持该标准，因此只需编写一次 skill，即可在兼容 agent 之间使用。规范 ↗定义 skill 文件夹中包含的内容，但不定义 skill 的存储位置或 agent 加载方式。

为什么使用 skill

模型知道很多内容，但不了解你团队的流程、约定或边缘情况。你可以将这些内容全部放入 system prompt，但这样每个 turn 都要为大多数任务不需要的说明付出成本。Skill 会打包这些上下文，让 agent 只在任务需要时加载。

Skill 适用于：

领域专业知识：法律审核清单、API error code 或品牌指南。
可重复的工作流：release 流程、incident runbook，或每次都应以相同方式运行的数据 pipeline。
复用：在 coding agent、chat agent 和 scheduled agent 中使用同一个 skill。
无需部署即可更改行为：当 skill 是 agent 在运行时读取的文件时，编辑文件就会更改 agent 的行为。

渐进式披露

Agent 分三个阶段加载 skill，因此 agent 可以用较小成本随时使用多个 skill：

阶段	Agent 加载的内容	触发时机	大致大小
1. 目录	每个 skill 的 `name` 和 `description`	session 启动时	每个 skill 50 到 100 个 token
2. 说明	完整的 `SKILL.md` 正文	任务与描述匹配时	建议不超过 5,000 个 token
3. 资源	Script、参考资料和 asset	说明引用它们时	不定

拥有 20 个 skill 的 agent 只需为 20 个简短目录条目付出成本，而不是 20 组说明。它只加载实际使用的 skill 的完整说明。

模型仅根据描述决定何时激活 skill。清晰说明 skill 使用时机的描述比任何其他字段都重要。

Skill 的结构

Skill 是一个目录，其名称与 skill 的 name 匹配：

release-notes/
├── SKILL.md          # Required: frontmatter and instructions
├── scripts/          # Optional: code the agent can run
├── references/       # Optional: documents the agent reads when needed
└── assets/           # Optional: templates, images, data files

SKILL.md 以 YAML frontmatter 开头，后跟 Markdown 指令：

---
name: release-notes
description: Turn a list of changes into release notes. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
license: Apache-2.0
compatibility: Requires Node.js 20 or later
metadata:
  author: my-team
  version: "1.2"
---

1. Read `references/style-guide.md`.
2. Run `scripts/format-release-notes.js` with one line per change.
3. Reply with the formatted notes.

Frontmatter 字段

字段	必需	规则
`name`	是	1 到 64 个字符。使用小写字母、数字和连字符。不能以连字符开头或结尾，也不能包含 `--`。必须与目录名称匹配。
`description`	是	1 到 1,024 个字符。说明 skill 的作用及其使用时机。
`license`	否	许可证名称或打包的许可证文件。
`compatibility`	否	1 到 500 个字符。环境要求，例如所需工具或网络访问。
`metadata`	否	字符串键到字符串值的 map，用于规范未定义的属性。
`allowed-tools`	否	skill 无需询问即可使用的工具列表，以空格分隔。此功能为实验性功能，各 Agent 的支持情况不同。

Agent 还可以读取自己的额外字段。例如，当设置 disable-model-invocation: true 时，一些 Agent 会对模型隐藏 skill。

正文和资源

规范不对 Markdown 正文设置规则。正文应保持专注：建议不超过 500 行。将详细资料移至 references/，并告诉 Agent 何时读取每个文件，例如：“如果 API 返回非 200 状态代码，请读取 references/api-errors.md。”

Skill 文件使用相对于 skill 目录的路径相互引用，例如 scripts/extract.py。从 SKILL.md 开始，引用应只深入一层。

脚本

skill 可以在 scripts/ 中打包脚本，并指示 Agent 运行它们。脚本可将脆弱的多步骤过程变为一条可靠命令。支持的语言取决于 Agent 的运行位置。

为 Agent 编写的脚本在满足以下条件时效果最佳：

绝不等待交互式输入。改为接受参数、环境变量或标准输入。
使用 --help 说明用法，并在错误消息中说明问题和可尝试的解决方法。
输出 JSON 等结构化内容，并将诊断信息与数据分开。
保持输出简短，或允许 Agent 使用 offset 请求更多内容。
可以安全地运行两次，因为 Agent 会重试。

编写优秀的 skill

从真实工作出发。 从你与 Agent 完成的任务或自己的 runbook 中提取的 skill，比通用建议更有用。
添加 Agent 不知道的内容。 跳过常见概念的解释。包含你的约定、要使用的工具以及容易出错的边缘情况。
像函数一样限定 skill 的范围。 每个 skill 只包含一个连贯的工作单元。范围太窄，一个任务会加载多个 skill；范围太宽，则难以准确激活 skill。
提供默认值，而不是菜单。 选择一种方法，只简要提及替代方案。
为模型编写描述。 将描述表述为采取行动的时机，例如“当用户要求……时使用”，并包含用户未明确说出领域名称的情况。
测试 skill。 使用真实 prompt 运行 skill，包括不应触发它的相似情况，然后进行修订。

信任

skill 会向 Agent 的上下文添加指令，其脚本可以运行代码。应像对待代码一样对待 skill：

仅从你信任的来源加载 skill。不受信任仓库中的 skill 可能会注入指令。
限制脚本可执行的操作。只授予其所需的工具、网络访问和文件访问权限。
审查 Agent 或用户可编辑的 skill 变更。

Agents SDK 中的 skill

Agents SDK 会读取 agents/skills 中的开放格式，并根据规范检查每个 SKILL.md。按照规范的 Agent 指南，它会加载违反规则的 skill 并记录警告，因此为其他 Agent 编写的 skill 仍可使用。无法使用的 skill（例如缺少描述的 skill）会被跳过。编写 skill 时，可使用 parseSkill() 解析并要求无警告，以进行检查。它从三个来源加载 skill：

来源	使用时机
Computer Workspace	skill 应是 Agent、用户或你的代码可在运行时添加和编辑的文件
R2	多个 Agent 共享在 Worker 外部管理的一组 skill
代码	测试，或随 Worker 一起提供的一小组固定 skill

SDK 使用多个 Agent 共享的 .agents/skills/ 文件夹约定，因此 Workspace 中的 /workspace/.agents/skills/ 存放 Agent 的 skill。模型通过 skill tool activate_skill 和 read_skill_resource 加载 skill。使用 Workspace backend 时，模型通过 Workspace exec tool 运行 skill 脚本。请参阅执行。