Agent Skills（简称 Skills）是智能体按需加载的指令与资料集合，以独立目录的形式组织和版本化管理。每个 Skill 的核心是一个 SKILL.md 文件，包含元数据和执行指令，智能体据此判断何时加载、如何执行。
为什么需要 Skills
Skills 将领域流程、工具用法和组织约束封装为可复用的文件集合。创建一次，即可在多个会话与任务中反复使用，确保执行一致性。Skills 具备以下核心特征：
按需加载：智能体仅在任务匹配时加载对应 Skill，避免无关指令占用上下文窗口。
可复用：同一 Skill 可在不同会话、不同任务中反复使用，无需重复编写指令。
可版本化：以文件形式存储在代码仓库中，支持 Git 版本管理、Code Review 和团队协作。
可组合：多个 Skill 可协同工作，智能体根据任务需要动态调度和组合。
Skill 的结构
每个 Skill 以独立目录的形式组织，通常遵循 Agent Skills 规范，采用以下结构：
my-skill/
├── SKILL.md # 必选：主文件，包含元数据与执行指令
├── references/ # 可选：深度参考资料、字段说明、决策表等
├── tools/ # 可选：辅助脚本、代码片段等
└── assets/ # 可选：示意图、截图、CSV 等静态资源SKILL.md 是唯一必选文件，由元数据和正文两部分组成：
元数据：至少包含
name（唯一标识符）和description（适用场景与触发条件）。智能体根据description判断是否加载该 Skill。正文：分步描述操作流程，可包含条件分支、检查点和预期输出，并定义明确的成功标准。
Skills 工作原理
Skills 采用渐进式披露机制。智能体不会一次性加载所有 Skill 的完整内容，而是分阶段按需加载，控制上下文占用：
发现：智能体启动任务时，仅加载各 Skill 元数据中的名称（
name）和描述（description），用于判断其与当前任务的相关性。激活：当任务与某个 Skill 的描述匹配时，智能体将该 Skill 完整的
SKILL.md文件读入上下文。执行：根据
SKILL.md中的指令执行操作，并按需加载引用的参考文件或执行附带的脚本。
Skill 仅提供操作指引，不能替代运行时环境与权限策略。是否允许执行配置变更或访问生产数据等操作，仍由平台的身份、策略和流程决定。
使用示例
以查询 ECS 实例状态为例，创建一个包含完整目录结构的 Skill 并验证效果。
步骤 1：创建 Skill 目录
在工程目录下新建 skills/ecs-query 文件夹，按以下结构组织文件：
ecs-query/
├── SKILL.md # 主文件：元数据与执行指令
├── references/
│ └── instance-status-codes.md # ECS 实例状态码与含义对照表
├── tools/
│ ├── query-instances.py # 调用 DescribeInstances 接口查询实例列表
│ └── export-csv.py # 将查询结果导出为 CSV 文件
└── assets/
└── output-template.md # 查询结果的输出格式模板创建 SKILL.md 文件：
---
name: ecs-query
description: 当用户需要查看 ECS 实例运行状态时，调用 DescribeInstances 接口查询并汇总输出。
---
# 查询 ECS 实例
## 步骤
1. 确认查询范围：地域和筛选条件（实例状态、标签等）。未指定地域时默认查询所有地域。
2. 执行 `tools/query-instances.py`，传入地域和筛选条件，获取实例列表。参考 `references/instance-status-codes.md` 解读状态码。
3. 参考 `assets/output-template.md` 中的模板，按以下格式输出查询结果：
- 查询概要（地域、实例总数）
- 实例列表（实例名称、实例 ID、状态、实例规格、IP 地址）
4. 如果用户需要导出结果，执行 `tools/export-csv.py` 生成 CSV 文件。SKILL.md 由两部分组成：顶部的 YAML 元数据（name 和 description）和 Markdown 正文。正文中通过相对路径引用 references/、tools/ 和 assets/ 中的文件，将参考数据、脚本和模板与执行逻辑分离。
步骤 2：导入工程
将 Skill 文件夹放置到智能体平台能够识别的路径下。常见平台的约定路径：
平台 | Skill 存放路径 | 说明 |
通义灵码 |
| 按约定目录自动发现 |
Cursor |
| 通过 Rules 或 Agent 配置加载 |
Claude Code |
| 自动扫描该目录下所有 Skill |
例如在 Claude Code 中，将 skills/ecs-query 文件夹移动到 .claude/skills/ 下即可完成导入。
步骤 3：验证效果
导入完成后，向智能体输入任务指令，智能体会根据各 Skill 的描述自动匹配并加载。
例如在 Claude Code 中输入：
帮我查一下华东1地域有哪些 ECS 实例在运行智能体匹配 ecs-query Skill，按 SKILL.md 中定义的格式返回结果：
ECS 实例查询结果
查询概要：
- 地域：华东1（杭州）
- 运行中实例：3 台
实例列表：
| 实例名称 | 实例 ID | 状态 | 规格 | IP 地址 |
| ------------- | -------------------- | ------ | --------------- | -------------- |
| web-server-01 | i-bp1a2b3c4d5e6f7g8h | 运行中 | ecs.g7.xlarge | 172.16.0.10 |
| api-gateway | i-bp2c3d4e5f6g7h8i9j | 运行中 | ecs.c7.large | 172.16.0.20 |
| db-backup | i-bp3d4e5f6g7h8i9j0k | 运行中 | ecs.r7.2xlarge | 172.16.0.30 |不同平台对 Skill 的文件格式、内容结构与安全策略可能存在差异，具体要求请参考对应平台文档。