title: “Agent Skills 规范说明”description: “Agent Skills 的完整格式规范。”目录结构一个技能是一个目录至少包含一个SKILL.md文件skill-name/ ├── SKILL.md # Required: metadata instructions (必需元数据 指令) ├── scripts/ # Optional: executable code (可选可执行代码) ├── references/ # Optional: documentation (可选文档) ├── assets/ # Optional: templates, resources (可选模板、资源) └── ... # Any additional files or directories (任何其他的文件或目录)SKILL.md格式SKILL.md文件必须包含 YAML frontmatter其后是 Markdown 内容。FrontmatterFrontmatter 是内容文件的头部元数据是整个内容系统的数据基础。你可以在 Markdown 文件的顶部添加 front matter。它是一个使用 YAML 格式定义元数据的块位于文件顶部的三个连字符---之间。字段必需约束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. ---带可选字段的示例--- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. license: Apache-2.0 metadata: author: example-org version: 1.0 ---name字段必需的name字段必须为 1-64 个字符仅可包含 Unicode 小写字母数字字符a-z、0-9和连字符-不得以连字符-开头或结尾不得包含连续的连字符--必须与父目录名一致有效示例name:pdf-processingname:data-analysisname:code-review无效示例name:PDF-Processing# uppercase not allowedname:-pdf# cannot start with hyphenname:pdf--processing# consecutive hyphens not alloweddescription字段必需的description字段必须为 1-1024 个字符应同时描述技能的用途以及使用时机应包含有助于智能体识别相关任务的具体关键词良好示例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.欠佳示例description:Helps with PDFs.license字段可选的license字段指明应用于该技能的许可证我们建议保持简短许可证名称或打包的许可证文件名示例license:Proprietary. LICENSE.txt has complete termscompatibility字段可选的compatibility字段若提供必须为 1-500 个字符仅当技能有特定环境要求时才应包含可标明目标产品、所需的系统软件包、网络访问需求等示例compatibility:Designed for Claude Code (or similar products)compatibility:Requires git,docker,jq,and access to the internetcompatibility:Requires Python 3.14 and uv大多数技能不需要compatibility字段。metadata字段可选的metadata字段一个从字符串键到字符串值的映射客户端可借此存储 Agent Skills 规范未定义的额外属性我们建议让键名具备一定的唯一性以避免意外的冲突示例metadata:author:example-orgversion:1.0allowed-tools字段可选的allowed-tools字段以空格分隔的字符串列出预先批准可运行的工具实验性。不同智能体实现对该字段的支持可能有所不同示例allowed-tools:Bash(git:*)Bash(jq:*)Read正文内容frontmatter 之后的 Markdown 正文包含技能指令。格式上没有任何限制可以写入任何有助于智能体有效完成任务的内容。推荐章节分步指令输入与输出示例常见边界情况请注意一旦智能体决定激活某个技能就会加载该文件的全部内容。对于较长的SKILL.md建议将部分内容拆分到被引用的文件中。可选目录scripts/存放智能体可执行的可运行代码。脚本应自包含或清晰地记录其依赖包含有用的错误提示妥善处理边界情况所支持的语言取决于智能体实现。常见选择包括 Python、Bash 和 JavaScript。references/存放智能体可按需阅读的补充文档REFERENCE.md- 详细的技术参考FORMS.md- 表单模板或结构化数据格式领域相关文件finance.md、legal.md等保持各个参考文件聚焦。智能体按需加载这些文件因此文件越小上下文消耗越少。assets/存放静态资源模板文档模板、配置模板图片图表、示例数据文件查找表、schema渐进式披露智能体渐进式地加载技能仅在任务需要时才拉取更多细节。技能的结构应充分利用这一点元数据约 100 tokens所有技能的name与description字段在启动时加载指令建议 5000 tokens技能被激活时加载完整的SKILL.md正文资源按需文件例如scripts/、references/或assets/中的文件仅在需要时加载请将主SKILL.md控制在 500 行以内。将详细参考资料移至单独的文件中。文件引用在技能中引用其他文件时请使用相对于技能根目录的路径See [the reference guide](references/REFERENCE.md) for details. Run the extraction script: scripts/extract.py文件引用请保持在距SKILL.md一层以内。避免过深的嵌套引用链。验证使用 skills-ref 参考库来验证你的技能skills-ref validate ./my-skill它会检查你的SKILL.mdfrontmatter 是否有效并遵循所有命名约定。