一、什么是 Agent SkillsAgent Skills以下简称 Skills是一种轻量级的开放格式用于通过专业知识和工作流扩展 AI 智能体的能力。简单来说Skill 就是一个包含SKILL.md文件的文件夹它封装了领域知识、最佳实践、工作流程和执行逻辑使 AI 能够高质量、稳定地完成特定任务。Skills 诞生的背景是传统 Prompt 方式的三大痛点不稳定模型对同一个 Prompt 的理解可能不同输出结果不一致不可复用每次都要重新编写 Prompt效率低不可组合难以将多个任务整合成复杂工作流Skills 将“如何做一件事”封装成 AI 可长期记住和调用的能力模块让执行更标准、稳定、可组合。核心特征按需加载智能体仅在任务匹配时加载对应 Skill避免无关指令占用上下文窗口可复用同一 Skill 可在不同会话、不同任务中反复使用可版本化以文件形式存储在代码仓库中支持 Git 版本管理可组合多个 Skill 可协同工作动态调度和组合二、设计哲学渐进式披露Progressive DisclosureSkills 最核心的设计理念是渐进式披露。智能体不会一次性加载所有 Skill 的完整内容而是分阶段按需加载以最小化上下文占用。整个加载过程分为四个层次阶段加载内容Token 消耗触发时机宣告Discovery仅 name description~100 tokens每次运行开始时加载Load完整 SKILL.md 正文 5,000 tokens任务匹配时读取资源Readreferences/ 等文档按需需要补充信息时运行脚本Runscripts/ 中的代码按需需要执行确定性操作时这种设计让 AI 的上下文窗口始终保持精简同时允许按需访问深层域知识。三、Skill 的目录结构3.1 最小结构一个 Skill 最精简的结构只需要一个SKILL.md文件my-skill/ └── SKILL.md # 必需元数据 执行指令3.2 完整结构一个生产级 Skill 的完整目录结构通常如下my-skill/ ├── SKILL.md # 必需入口文件含元数据与执行指令 ├── scripts/ # 可选可执行代码Python/Bash/JS等 │ ├── main.py │ └── requirements.txt # Python 依赖声明 ├── references/ # 可选深度参考资料、文档 │ ├── api-reference.md │ └── policy-faq.md ├── templates/ # 可选模板文件 │ └── report-template.md ├── assets/ # 可选静态资源图标、字体、图片等 │ └── logo.png └── workflows/ # 可选工作流定义非官方标准社区实践 └── approval-flow.yaml3.3 各目录职责速查表目录职责典型内容加载方式SKILL.md入口 核心流程触发条件、分步指令、边界规则Skill 激活时加载scripts/确定性操作解析、转换、校验、排序等脚本按需执行references/参考资料API 文档、政策条款、决策表按需读取到上下文templates/输出模板报告模板、邮件模板、表单按需加载assets/静态资源图片、字体、品牌素材用于输出不加载到上下文workflows/工作流定义多步骤流程的 YAML/JSON 定义按需加载四、SKILL.md 文件详解SKILL.md是每个 Skill 的唯一必选文件由YAML 前置元数据和Markdown 正文两部分组成。4.1 YAML 前置元数据Frontmatter---name:expense-reportdescription:File and validate employee expense reports according to company policy. Use when asked about expense submissions,reimbursement rules,or spending limits.license:Apache-2.0compatibility:Requires python3,pandasmetadata:author:finance-teamversion:2.1allowed-tools:read_file write_file---字段说明字段必需说明name✅ 是最多 64 字符。仅小写字母、数字和连字符。不得以连字符开头或结尾不得包含连续连字符。必须与父目录名称匹配description✅ 是最多 1024 字符。描述技能的作用和使用场景。应包含帮助智能体识别相关任务的关键词license❌ 否许可证名称或对捆绑许可证文件的引用compatibility❌ 否最多 500 字符。环境要求预期产品、系统包、网络访问等metadata❌ 否其他元数据的任意键值映射作者、版本等allowed-tools❌ 否技能可以使用的预先批准的工具列表实验性name 命名规则1-64 个字符只能用 Unicode 小写字母、数字和连字符a-z、0-9、-不能以-开头或结尾不能有连续连字符--✅ 有效示例pdf-processing、data-analysis、code-review❌ 无效示例PDF-Processing有大写、-pdf以连字符开头、pdf--processing连续连字符description 编写要点1-1024 个字符不能为空具体说明技能的功能和使用场景包含帮助匹配的关键词避免空泛形容词和宣传语4.2 Markdown 正文frontmatter 后面的 Markdown 正文包含技能的核心执行指令——分步指导、输入输出示例、常见边缘情况等。编写原则使用指令性语言动词开头而非第二人称保持SKILL.md500 行以下将详细的参考资料移动到references/等单独文件中避免重复信息只存在于一个地方示例# Expense Report Processing ## When to use this skill Use when users ask to file expense reports, check reimbursement status, or inquire about spending limits. ## Core workflow 1. Collect employee info (name, ID, department) 2. Validate expense amount against policy (see references/policy.md) 3. Run scripts/validate.py to check format compliance 4. Generate report using templates/report-template.md 5. Submit for approval ## Edge cases - Amount $1000 requires manager approval - International receipts require currency conversion五、可选资源目录详解5.1 scripts/ —— 可执行脚本用途存放需要确定性可靠性的可执行代码。何时使用当某个操作需要稳定、机械、可重复执行时如数据解析、格式转换、校验、排序、去重等应交给脚本而非让 AI 临场发挥。典型内容Python 脚本.pyBash 脚本.shJavaScript/TypeScript 脚本.js/.ts依赖管理Python在scripts/下放置requirements.txtNode.js在scripts/下放置package.json示例scripts/ ├── validate.py ├── export_csv.py └── requirements.txt # pandas1.3.0, openpyxl关键原则scripts/ 里的代码负责不需要语义判断、价值判断、风格判断的稳定动作。5.2 references/ —— 参考资料用途存放旨在根据需要加载到上下文中以辅助 AI 思考和决策的文档。何时使用当信息是参考性质的AI 不一定每次都需要时。将长篇文档放入references/可以保持SKILL.md精简。典型内容API 文档数据库 Schema公司政策条款决策表术语表字段说明最佳实践指南示例references/ ├── policy.md # 公司报销政策 ├── api-reference.md # API 接口文档 ├── status-codes.md # 状态码含义对照表 └── glossary.md # 术语表优势AI 只在确定需要时才加载这些文档避免无关内容占用上下文。5.3 templates/ —— 模板文件用途存放用于生成输出的模板文件。典型内容报告模板Markdown/HTML邮件模板表单模板代码样板示例templates/ ├── weekly-report.md ├── email-notification.txt └── invoice-template.html使用方式SKILL.md中引用模板指导 AI 在生成输出时参照模板格式。5.4 assets/ —— 静态资源用途存放不打算加载到上下文中、而是用于 AI 生成输出中的文件。与 templates/ 的区别templates/文本模板AI 会读取并填充内容assets/静态资源直接用于输出或引用如图片、字体典型内容品牌 Logo图标、图片字体文件CSS 样式文件PDF 样板示例assets/ ├── company-logo.png ├── brand-font.ttf └── letterhead.pdf5.5 workflows/ —— 工作流定义说明workflows/并非 Agent Skills 官方规范的强制或推荐目录。它是社区实践中出现的一种组织方式用于存放多步骤工作流的定义文件。用途当 Skill 包含复杂的多步骤流程时可以用 YAML/JSON 等格式将工作流定义独立存放便于维护和版本管理。典型内容工作流 YAML/JSON 定义步骤间的依赖关系审批流程配置示例workflows/ ├── approval-flow.yaml └──>六、工作原理完整执行流程以一个实际场景为例展示 Skill 的完整工作流程场景ECS 实例查询 Skill目录结构ecs-query/ ├── SKILL.md ├── references/ │ └── instance-status-codes.md ├── scripts/ │ ├── query-instances.py │ └── export-csv.py └── assets/ └── output-template.md执行流程发现阶段智能体启动时仅加载ecs-query的name和description知道有这个技能可用激活阶段用户说“帮我查一下所有运行中的 ECS 实例”description 匹配智能体加载完整的SKILL.md执行阶段智能体按照SKILL.md中的指令操作确认查询范围地域、筛选条件执行scripts/query-instances.py获取实例列表参考references/instance-status-codes.md解读状态码参照assets/output-template.md格式化输出如需导出执行scripts/export-csv.py七、最佳实践7.1 结构与内容实践说明具体明确的 description清楚说明 Skill 何时应该被使用包含触发关键词指令性语言使用动词开头的指令“提取”、“验证”、“生成”而非第二人称按需加载将长篇文档放入references/避免SKILL.md臃肿保持 SKILL.md 精简控制在 500 行以内避免重复信息应存在于SKILL.md或引用文件中不要两处都有确定性操作脚本化解析、转换、校验等稳定动作交给scripts/7.2 Skill 与长 Prompt 的区别对比项长 PromptSkill核心形态一大段指令有入口、有资料、有脚本的目录主要依赖模型每次重新理解模型按设计好的路径执行内容组织背景、规则、模板混在一起流程、材料、脚本分开放稳定动作交给模型临场发挥交给脚本或明确工具适合场景一次性任务重复流程、固定格式7.3 创建 Skill 的流程理解需求明确 Skill 的使用场景和触发条件拆解工作流分析哪些是流程、哪些是材料、哪些是脚本规划资源分析是否需要脚本、参考文档、模板或静态资源创建目录在.codebuddy/skills/或对应平台目录下创建编写 SKILL.md填写 YAML 元数据 Markdown 指令引用打包资源在指令中正确引用 scripts/、references/ 等八、总结Agent Skills 通过标准化目录结构、渐进式披露加载和职责分离的设计将 AI 的能力从“每次重新理解 Prompt”升级为“按设计好的路径专业执行”。其核心要点可概括为一个入口SKILL.md是唯一必选文件包含元数据和执行指令四类资源scripts/确定性操作、references/参考资料、templates/输出模板、assets/静态资源一种哲学渐进式披露按需加载最小化上下文占用一次开发多端部署个人、团队、企业均可受益掌握 Skills 的本质不是把“上次成功的对话”写成更长的 Prompt而是将重复流程拆解为结构清晰、职责分明、可维护可版本化的能力模块。