Agent Skills 官方规范

什么是 SkillsAgent Skills代理技能是一种轻量级的开源格式旨在通过特定的专业知识和工作流来扩展 AI 代理的能力。从本质上讲一个 Skill技能 就是一个包含 SKILL.md 文件的文件夹。该文件包含元数据至少包含 name 名称 和 description 描述以及指导代理如何执行特定任务的指令。Skills 还可以打包脚本、模板和参考资料。my-skill/# 技能文件夹├── SKILL.md# 必需指令 元数据├── scripts/# 可选可执行代码├── references/# 可选文档资料└── assets/# 可选模板、资源文件Skills 的工作原理Skills 采用渐进式披露Progressive Disclosure 机制来高效管理上下文Context发现Discovery代理在启动时仅加载每个可用 Skill 的名称和描述。这足以让代理知道该技能何时可能相关而无需加载全部细节。激活Activation当任务与某个 Skill 的描述匹配时代理会将完整的 SKILL.md 指令读入上下文中。执行Execution代理遵循这些指令并根据需要选择性地加载引用的文件或执行打包的代码。这种设计让代理保持了快速响应同时又能按需访问更多的上下文信息。SKILL.md 文件详解每一个 Skill 都始于一个 SKILL.md 文件该文件包含 YAML 前置元数据YAML frontmatter 和 Markdown 格式的指令--- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. --- # PDF 处理 (PDF Processing) ## 何时使用此技能 当用户需要处理 PDF 文件时请使用此技能... ## 如何提取文本 1. 使用 pdfplumber 进行文本提取... ## 如何填写表单 ...以下前置元数据Frontmatter必须位于 SKILL.md 的顶部name: 一个简短的标识符。description: 何时使用此技能的说明。Markdown 正文部分包含具体的执行指令其结构和内容没有特定的限制。这种简单的格式具有以下几个关键优势自文档化Self-documenting技能的作者或用户可以直接阅读 SKILL.md 来理解其功能这使得 Skills 非常容易进行审查Audit和改进。可扩展ExtensibleSkills 的复杂程度可以从纯文本指令扩展到包含可执行代码、资产和模板的复杂结构。可移植PortableSkills 本质上就是文件因此非常容易进行编辑、版本控制和共享。规范说明 (Specification)Agent Skills 的完整格式规范。目录结构一个 Skill技能本质上就是一个目录其中至少必须包含一个 SKILL.md 文件skill-name/ # 技能目录名 ├── SKILL.md # 必需元数据 执行指令 ├── scripts/ # 可选可执行代码 ├── references/ # 可选文档资料 ├── assets/ # 可选模板、资源文件 └── ... # 任何其他文件或子目录SKILL.md 格式SKILL.md 文件必须包含 YAML 前置元数据YAML frontmatter后跟 Markdown 格式的内容。前置元数据 (Frontmatter)字段 (Field)是否必需约束与说明name是最长 64 字符。仅允许小写字母、数字和连字符。不能以连字符开头或结尾。description是最长 1024 字符。不能为空。需描述技能的功能及适用场景。license否许可证名称或指向捆绑的许可证文件的引用。compatibility否最长 500 字符。标明环境需求如目标产品、系统包、网络访问等。metadata否任意键值对映射用于存储额外的元数据。allowed-tools否(实验性) 技能可使用的预批准工具的空格分隔列表。--- name: skill-name description: A description of what this skill does and when to use it. ---包含可选字段的示例 (Example with optional fields)---name:pdf-processingdescription:Extract PDF text,fill forms,merge files. Use when handling PDFs.license:Apache-2.0metadata:author:example-orgversion:1.0---name 字段必填的 name 字段需遵守以下规则1长度限制1-6 4个字符。2字符限制仅允许 Unicode 小写字母数字字符 (a-z) 和连字符 (-)。3位置限制不能以连字符 (-) 开头或结尾。4格式限制不能包含连续的连字符 (–)。5一致性必须与父目录名称匹配。name:pdf-processingdescription 字段必填的 description 字段需遵守以下规则1长度限制1-1024 个字符。2内容要求应描述技能的功能以及何时使用它。3关键词应包含特定的关键词帮助 Agent 识别相关的任务。description:Extracts text and tables from PDF files,fills PDF forms,and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs,forms,or document extraction.license 字段可选的 license 字段1用于指定应用于该技能的许可证。2建议保持简短直接写许可证名称或指向捆绑的许可证文件名。license:Proprietary. LICENSE.txt has complete termscompatibility 字段可选的 compatibility 字段1长度限制如果提供需在 1-500 个字符之间。2使用场景仅当你的技能有特定的环境需求时才包含此字段。3内容可以标明目标产品、所需的系统包、网络访问需求等。compatibility:Designed for Claude Code (or similar products)metadata 字段可选的 metadata 字段1从字符串键到字符串值的映射。2客户端Clients可以使用它来存储 Agent Skills 规范中未定义的额外属性。3建议使用具有合理唯一性的键名以避免意外冲突。metadata:author:example-orgversion:1.0allowed-tools 字段可选的 allowed-tools 字段1定义预批准可运行工具的空格分隔列表。2状态实验性Experimental。不同 Agent 实现对该字段的支持可能有所不同。allowed-tools:Bash(git:*)Bash(jq:*)Read正文内容 (Body content)YAML 前置元数据之后的 Markdown 正文包含具体的技能指令。此处没有格式限制。你可以编写任何有助于 Agent 有效执行任务的内容。建议包含的章节分步操作指南 (Step-by-step instructions)输入和输出的示例 (Examples of inputs and outputs)常见的边缘情况 (Common edge cases)注意一旦 Agent 决定激活某个 Skill它将加载整个文件。如果内容过长建议将其拆分为引用的外部文件。可选目录 (Optional directories)scripts/包含 Agent 可以运行的可执行代码。脚本应满足以下要求1自包含或明确记录依赖项。2包含有用的错误信息。3优雅地处理边缘情况。4支持的语言取决于 Agent 的具体实现。常见的选项包括 Python、Bash 和 JavaScript。references/包含 Agent 在需要时可以读取的额外文档资料1REFERENCE.md - 详细的技术参考。2FORMS.md - 表单模板或结构化数据格式。3领域特定文件如 finance.md, legal.md 等。请保持单个 参考文件 的内容集中。Agent 会按需加载这些文件因此较小的文件意味着占用更少的上下文Context。assets/包含静态资源1模板文档模板、配置模板。2图片图表、示例。3数据文件查找表、模式定义。渐进式披露 (Progressive disclosure)Skills 应该为了高效利用上下文而进行结构化设计元数据 (Metadata) (100 tokens)启动时加载所有可用技能的 name 和 description。指令 (Instructions) (建议 5000 tokens)当技能被激活时加载完整的 SKILL.md 正文。资源 (Resources) (按需)仅在需要时加载文件例如 scripts/、references/ 或 assets/ 中的文件。建议保持你的主 SKILL.md 文件在 500 行以内。将详细的参考资料移动到单独的文件中。文件引用 (File references)在技能中引用其他文件时请使用相对于技能根目录的路径See [the reference guide](references/REFERENCE.md) for details. Run the extraction script: scripts/extract.py保持文件引用距离 SKILL.md 仅一层深度。避免深度嵌套的引用链。验证 (Validation)使用 skills-ref 参考库来验证你的 Skillsskills-ref validate ./my-skillpython代码示例frompathlibimportPathfromskills_refimportvalidate,read_properties,to_prompt# Validate a skill directoryproblemsvalidate(Path(my-skill))ifproblems:print(Validation errors:,problems)# Read skill propertiespropsread_properties(Path(my-skill))print(fSkill:{props.name}-{props.description})# Generate prompt for available skillspromptto_prompt([Path(skill-a),Path(skill-b)])print(prompt)该命令会检查你的 SKILL.md 前置元数据是否有效并是否遵循所有命名约定。本库仅用于演示目的不建议在生产环境中使用。FAQ什么是 SkillsSkills 就是 AI agent的「专家模式」。每个 Skill是一个 SKILL.md 文件教你的agent怎么做某项任务-不用重复输入指令。Skills 和提示词有什么区别提示词用完就没了。Skills 是永久的安装一次agent 就永远记得怎么做这件事。什么是三层加载机制先加载元数据→触发时加载指令→需要时才加载额外资源。SKILL.md 里要写什么YAML 前言(name description必填)然后是 markdown 格式的指令、示例和边界情况。旁边可以放 scripts/、references/、assets/文件夹。Skills 可以在哪里使用Claude Code、Codex CLI、Cursor、GeminiCLI、Windsurf、GitHub、Copilot、OpenClaw等。怎么手动创建 Skill新建文件夹写一个SKILL.md:YAML 前言填name descriptionmarkdown写指令按需加 scripts/和references/文件夹。什么是 Agent Skills 开放标准由agentskills.io发布的开放规范让AI代理技能可移植。写一次各种平台通用。Skills 如何提升 token 效率Skills 预加载上下文省去重复指令token用量最多减少70%。