一、什么是 Agent Skills
Agent Skills（以下简称 Skills）是一种轻量级的开放格式，用于通过专业知识和工作流扩展 AI 智能体的能力。简单来说，Skill 就是一个包含SKILL.md文件的文件夹，它封装了领域知识、最佳实践、工作流程和执行逻辑，使 AI 能够高质量、稳定地完成特定任务。
Skills 诞生的背景是传统 Prompt 方式的三大痛点：
- 不稳定：模型对同一个 Prompt 的理解可能不同，输出结果不一致
- 不可复用：每次都要重新编写 Prompt，效率低
- 不可组合：难以将多个任务整合成复杂工作流
Skills 将“如何做一件事”封装成 AI 可长期记住和调用的能力模块，让执行更标准、稳定、可组合。
核心特征
- 按需加载：智能体仅在任务匹配时加载对应 Skill，避免无关指令占用上下文窗口
- 可复用：同一 Skill 可在不同会话、不同任务中反复使用
- 可版本化：以文件形式存储在代码仓库中，支持 Git 版本管理
- 可组合：多个 Skill 可协同工作，动态调度和组合
二、设计哲学：渐进式披露（Progressive Disclosure）
Skills 最核心的设计理念是渐进式披露。智能体不会一次性加载所有 Skill 的完整内容，而是分阶段按需加载，以最小化上下文占用。
整个加载过程分为四个层次：
| 阶段 | 加载内容 | Token 消耗 | 触发时机 |
|---|---|---|---|
| 宣告（Discovery） | 仅 name + description | ~100 tokens | 每次运行开始时 |
| 加载（Load） | 完整 SKILL.md 正文 | < 5,000 tokens | 任务匹配时 |
| 读取资源（Read） | references/ 等文档 | 按需 | 需要补充信息时 |
| 运行脚本（Run） | scripts/ 中的代码 | 按需 | 需要执行确定性操作时 |
这种设计让 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.1"allowed-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 脚本（
.py） - Bash 脚本（
.sh） - JavaScript/TypeScript 脚本（
.js/.ts）
依赖管理：
- Python：在
scripts/下放置requirements.txt - Node.js：在
scripts/下放置package.json
示例：
scripts/ ├── validate.py ├── export_csv.py └── requirements.txt # pandas>=1.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 的区别
对比项 长 Prompt Skill 核心形态 一大段指令 有入口、有资料、有脚本的目录 主要依赖 模型每次重新理解 模型按设计好的路径执行 内容组织 背景、规则、模板混在一起 流程、材料、脚本分开放 稳定动作 交给模型临场发挥 交给脚本或明确工具 适合场景 一次性任务 重复流程、固定格式
7.3 创建 Skill 的流程
- 理解需求：明确 Skill 的使用场景和触发条件
- 拆解工作流：分析哪些是流程、哪些是材料、哪些是脚本
- 规划资源：分析是否需要脚本、参考文档、模板或静态资源
- 创建目录：在
.codebuddy/skills/或对应平台目录下创建 - 编写 SKILL.md：填写 YAML 元数据 + Markdown 指令
- 引用打包资源：在指令中正确引用 scripts/、references/ 等
八、总结
Agent Skills 通过标准化目录结构、渐进式披露加载和职责分离的设计，将 AI 的能力从“每次重新理解 Prompt”升级为“按设计好的路径专业执行”。
其核心要点可概括为：
- 一个入口：
SKILL.md是唯一必选文件，包含元数据和执行指令 - 四类资源：
scripts/（确定性操作）、references/（参考资料）、templates/（输出模板）、assets/（静态资源） - 一种哲学：渐进式披露，按需加载，最小化上下文占用
- 一次开发：多端部署，个人、团队、企业均可受益
掌握 Skills 的本质，不是把“上次成功的对话”写成更长的 Prompt，而是将重复流程拆解为结构清晰、职责分明、可维护可版本化的能力模块。
)