agent-skills

Agent Skills 标准参考

本技能介绍 Agent Skills 开放格式——一种为 AI Agent 提供新能力和专业知识的标准化方式。在此仓库中创建或编辑技能时，请遵循此工作流。

权威来源：agentskills.io/specification。随附的规范是当前工作快照；需要确认是否为最新版本时，请查阅权威来源。

---

目录结构

技能是一个目录，至少包含一个 SKILL.md 文件：

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── evals/            # Required for new skills in this repository
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

必需工作流

创建或编辑技能

1. 在更改 SKILL.md 元数据或目录结构之前，阅读规范。
2. 以真实的领域知识、项目产物和观察到的失败模式为指导编写说明。设计或实质性修订说明时，请阅读最佳实践。
3. 让技能成为一个连贯且可触发的单元。只将必要说明放入 SKILL.md；将条件性细节放入专门的参考文件，并明确说明何时阅读每个文件。
4. 使用精确的 description，说明技能的作用、适用场景和不适用场景。对于存在明显重叠的技能，请在 ## When not to use 部分指出最接近的替代方案或前置条件。至少使用三个应触发提示词和两个不应触发的近似提示词测试边界；将这些特定于测试框架的触发检查与可移植的输出质量评估分开。请阅读优化描述，了解触发设计。
5. 每个新技能都要创建 evals/evals.json，其中至少包含五个有代表性的输出质量测试用例。每个用例都需要一个真实的提示词、预期结果和可观察的断言。请加入能够检验高风险或模糊行为的边界情况。请阅读评估技能，了解评估格式和迭代工作流。
6. 打包可执行代码时，请阅读使用脚本。在技能中记录前置条件和非交互式调用方法。
7. 交付前，运行此技能中的验证检查，并修正所有发现的问题。

审查技能

1. 根据规范，验证必需的 frontmatter、字段约束、父目录与名称匹配情况以及 YAML 语法。
2. 检查描述是否同时明确了正向和负向触发边界、工作流是否可执行，以及资源引用是否有条件且可访问。
3. 检查所有脚本是否记录了依赖项、是否接受安全的非交互式输入、是否提供清晰的错误信息，并在适用时输出结构化结果。
4. 对于此仓库，还需核实必需的面向用户的 README.md 是否包含标题、Why Install This Skill、What You Get、Quick Start（确实仅供参考的情况除外）、Triggers 和 Requirements。内容应面向用户、简洁，不包含仅供 Agent 使用的说明。
5. 核实每个新技能都有包含至少五个输出质量测试用例的 evals/evals.json，并检查预期结果和断言是否能测试有意义的行为。对于缺少 eval 的现有技能，指出此问题，但不要仅因这一历史遗留问题而阻止审查。宣布工作完成前，请阅读评估技能。

客户端实现工作

在 Agent 产品中实现技能发现、激活或上下文管理时，请阅读客户端实现指南。请勿将搜索路径等客户端约定视为通用格式要求。

SKILL.md 格式

SKILL.md 文件必须包含 YAML frontmatter，后接 Markdown 正文内容。

Frontmatter 字段

字段	必填	限制
name	是	最多 64 个字符。仅允许小写字母、数字和连字符。不能以连字符开头或结尾。必须与父目录名称一致。
description	是	最多 1024 个字符。不能为空。描述该技能的用途及使用时机。
license	否	许可证名称或对捆绑许可证文件的引用。
compatibility	否	最多 500 个字符。说明环境要求。
metadata	否	任意键值映射。
allowed-tools	否	以空格分隔的预批准工具字符串。（实验性）

name 字段规则

• 1–64 个字符
• 仅允许小写 Unicode 字母数字字符（a-z、0-9）和连字符（-）
• 不能以连字符开头或结尾
• 不能包含连续连字符（--）
• 必须与父目录名称一致

description 字段规则

• 1–1024 个字符
• 应描述该技能的用途及使用时机
• 应包含具体关键词，以帮助 Agent 识别相关任务

compatibility 字段规则

• 如果存在，必须为 1–500 个字符
• 仅在存在具体环境要求时才包含，例如必需的产品、系统包、网络访问或运行时

metadata 字段规则

• 必须是字符串键到字符串值的映射
• 使用足够独特的键，以避免与其他客户端或工具冲突

正文内容

Markdown 正文除了应对 Agent 有帮助外，没有格式限制。建议包含以下部分：

• 分步说明 — Agent 应遵循的操作步骤
• 输入和输出示例 — 输入和输出数据的形式
• 常见边缘情况 — Agent 在没有指导时可能无法正确处理的情况
• 注意事项 — 与环境相关、可能违背合理假设的事实

将 SKILL.md 控制在 500 行和 5000 个词元以内。将详细的参考资料移至 references/ 中的独立文件。

渐进式披露

Agent 分三个阶段加载技能：

1. 元数据（约 100 个词元）：启动时为所有技能加载 name 和 description
2. 说明（建议少于 5000 个词元）：激活时加载完整的 SKILL.md
3. 资源（按需）：按需加载 scripts/、references/、assets/ 中的文件

支持目录

scripts/

Agent 可运行的可执行代码。脚本应：

• 独立运行，或清晰说明依赖项
• 提供有帮助的错误消息
• 妥善处理边缘情况
• 使用相对于技能根目录的路径（例如 scripts/extract.py）
• 明确说明用途：指出“运行此脚本”或“将其作为参考资料阅读”，绝不要让 Agent 猜测捆绑文件是可执行文件还是示例

references/

按需加载的补充文档。每个文件应聚焦于特定主题——Agent 会在收到指示后加载这些文件，因此较小的文件更节省上下文。

• references/ 下的每个文件不得超过 60,000 个字符。当参考资料超过上限时，将其拆分为主题明确的文件（例如 references/<topic>-a.md、references/<topic>-b.md），并更新 SKILL.md，确保每个新文件都可访问，且按需加载说明指出正确的文件。

assets/

静态资源：模板、图像、数据文件、架构。

evals/

用于评估技能输出质量的可移植用例。此仓库中的新技能必须包含至少有五个用例的 evals/evals.json；仅用于触发检查的用例应放在特定测试框架的测试集，而不是此文件中。

文件引用

引用其他文件时，使用相对于技能根目录的路径：

See [the specification](references/specification.md) for details.

Run a bundled script:
scripts/<script-name>

将文件引用限制在 SKILL.md 下一级。避免使用深层嵌套的引用链。

编写有效的描述

description 字段是自动选择技能的主要机制。客户端也可以支持显式激活。请遵循以下原则：

• 使用祈使句。 使用“在……时使用此技能”，而不是“此技能会……”。
• 关注用户意图，而非实现方式。 描述用户想要实现什么。
• 宁可明确一些。 明确列出此技能适用的情境。
• 保持简洁。 几句话到一小段为宜。

最佳实践

从真实经验出发

在创建技能时融入领域专属背景。以真实项目资料（操作手册、API 规范、代码审查评论、实际故障案例）为基础的技能，效果优于根据通用知识综合生成的技能。

明智地使用上下文

重点说明 Agent 在没有该技能时不会知道的内容：项目专属约定、领域专属流程、不明显的边界情况。不要解释 Agent 已经了解的通用概念。

调整控制力度

• 多种方法都可行时，给予自由——说明 原因，而不只是 做什么
• 操作易出错或必须遵循特定顺序时，明确规定做法
• 让规定的严格程度与出错风险相匹配：对于每次都必须准确执行的步骤，优先使用 scripts/ 中的确定性脚本，而不是让 Agent 每次运行时自行发挥。测试只能发现你事先想到要检查的问题；脚本则能彻底消除猜测
• 提供默认方案，而非选项菜单——选定一种方法，并简要提及其他方案
• 优先说明流程，而非罗列要求——教会 Agent 如何处理一类问题，而不是针对某个实例说明要产出什么

设计连贯的单元

像设计函数一样划分技能的范围：每个技能都是一个能与其他技能良好组合的连贯工作单元。范围太窄 → 一个任务需要多个技能。范围太宽 → 难以精准激活。

使用注意事项章节

最有价值的内容往往是特定环境中的修正——如果没有特别说明，Agent 就会出错的地方。当 Agent 犯错时，将修正方法添加到注意事项章节。

提供输出模板

当输出需要遵循特定格式时，请在正文或 assets/ 中提供模板。Agent 擅长根据具体结构进行模式匹配。

采用第三方技能

技能是可执行能力：技能激活时，其指令和脚本会使用 Agent 的权限运行，包括 shell 访问权限、文件系统访问权限和凭据。在运行你未编写的技能（来自注册表、同事或 LLM 生成）之前，请阅读审查第三方技能，并像对待其他依赖项一样检查它：核查来源，阅读正文和每个脚本，并检查该技能会访问哪些外部资源。

验证

使用 skills-ref 参考库验证技能：

skills-ref validate ./my-skill

此操作会检查 SKILL.md 的 frontmatter 是否有效，以及是否遵循所有命名约定。

对于此代码库，还要运行随附的全仓库检查器：

ruby scripts/validate-skills.rb

它会检查规范顶层技能和技能包中的技能是否符合 frontmatter、支持的字段、行数限制、本地链接和必需 README 章节等要求。有意排除 agent-council/profiles/skills/ 下的供应商配置文件技能，因为它们遵循源代码库的约定。

如果无法使用 skills-ref，请勿声称验证器运行成功。请手动执行并报告等效的结构检查，或者在任务允许时安装并运行参考验证器。