第一章：Agent Skills 概述

1.1 什么是 Agent Skills？

Agent Skills（智能体技能）是 Anthropic 推出的开放标准能力扩展机制，用于将特定任务的指令、脚本和参考资源封装成可复用的能力包，供 AI 智能体按需加载和执行。

简单来说，Skill 就是一个教 AI 怎么干活的「技能手册」。它让 AI 从“会聊天”变成“会做事”。

核心定义：Agent Skills 是模块化的、可复用的能力扩展包，专为通用 AI Agent（如 Claude Code、Cursor 等）设计。每个 Skill 打包了完整的“做事方法”：包括任务指导指令、执行流程、最佳实践、可选的代码脚本、参考文档、素材资源等。

1.2 为什么需要 Agent Skills？

使用 AI 时常见的一个大问题是上下文膨胀——给 AI 提供了过多的信息，导致其难以完成任务。Agent Skills 通过以下方式解决此问题：

特征	说明
按需加载	智能体仅在任务匹配时加载对应 Skill，避免无关指令占用上下文窗口
可复用	同一 Skill 可在不同会话、不同任务中反复使用，无需重复编写指令
可版本化	以文件形式存储在代码仓库中，支持 Git 版本管理、Code Review 和团队协作
可组合	多个 Skill 可协同工作，智能体根据任务需要动态调度和组合

1.3 Skills 与其他技术的区别

技术	本质	作用范围	持久性
Prompts	对话级指令	单次任务	临时
Agent Skills	领域知识包	可复用能力	持久化
MCP	工具连接协议	外部系统对接	持久化

用软件架构来理解：

• 应用层：Agent Skills（领域知识、工作流、最佳实践）
• 传输层：MCP（标准化接口、工具调用）
• 基础设施层：数据库、API、文件系统

如果说 MCP 为智能体提供了“手”来操作工具，那么 Skills 就提供了“操作手册”或“SOP”，教导智能体如何正确使用这些工具。

第二章：Agent Skills 的核心机制——渐进式披露

Agent Skills 最核心的创新是渐进式披露（Progressive Disclosure） 的三层加载机制：

第一层：发现阶段（~100 tokens）

智能体启动时，仅加载所有技能的元数据（name + description）。这部分常驻上下文，用于判断“这个任务需不需要用我”。

这意味着你可以安装 20+ 个技能包，AI 启动时每个只占约 100 tokens。

第二层：激活阶段（< 5000 tokens）

当用户消息与元数据匹配时，智能体加载完整的 SKILL.md 指令文档。

第三层：执行阶段（按需加载）

按需动态访问引用的脚本（scripts/）、参考文档（references/）和资源文件（assets/）。脚本只执行不进上下文，输出结果才进入上下文。

运行流程示例

用户发任务 → Agent 匹配 Level 1 元数据 → 决定调用 Skill → 加载 Level 2 指令 → 根据指令规划 → 按需调用 Level 3 资源/脚本 → 执行 → 观察结果 → 循环直到完成。

第三章：Skill 的文件结构

每个 Skill 以独立目录的形式组织，遵循 Agent Skills 规范。

3.1 标准目录结构

my-skill/
├── SKILL.md          # 必选：主文件，包含元数据与执行指令
├── scripts/          # 可选：可执行代码（Python、Bash、JS等）
├── references/       # 可选：参考文档、规范、知识材料
└── assets/           # 可选：模板、图片、配置文件等静态资源

3.2 SKILL.md 文件详解

SKILL.md 是唯一必选文件，由元数据和正文两部分组成。

元数据（YAML Frontmatter）

必须包含 name 和 description 字段：

---
name: code-reviewer
description: Review code for security issues and best practices. Use when user asks for code review.
---

• name：技能的唯一标识符
• description：适用场景与触发条件，智能体据此判断是否加载该 Skill

正文（Markdown 指令）

分步描述操作流程，可包含条件分支、检查点和预期输出，并定义明确的成功标准。建议不超过 500 行。

3.3 完整示例

以下是一个完整的代码审查 Skill 示例：

---
name: code-reviewer
description: Review code for security issues and best practices. Use when user asks for code review.
---

# Code Review Skill

## Instructions

1. 检查常见安全漏洞（SQL 注入、XSS、命令注入等）
2. 评估性能问题和代码异味
3. 检查代码风格一致性
4. 给出具体的改进建议和代码示例

## Output Format

每个问题按以下格式输出：
- **Severity**: Critical / High / Medium / Low
- **Location**: 文件名:行号
- **Issue**: 问题描述
- **Fix**: 修复建议

## Examples

输入: "Review this Python function for security issues"
输出: 按格式给出安全审查报告

第四章：如何创建和使用 Agent Skills

4.1 创建 Skill

方式一：手动创建

1. 在项目目录下创建 .agents/skills/ 文件夹
2. 为每个 Skill 创建一个子文件夹
3. 在子文件夹中创建 SKILL.md 文件
4. （可选）添加 scripts/、references/、assets/ 子文件夹

方式二：使用 AI 辅助生成

以 Cursor 为例：

1. 打开 Cursor 设置 → 选择 Rules、Skills、Subagents 标签页
2. 点击新建 Skill
3. 在对话框中输入需求描述，例如：“根据需求文档生成测试用例，需要覆盖正向、逆向、异常、并发场景”
4. AI 会自动生成技能草稿并写入 SKILL.md
5. 与 AI 交互调整细节（输出格式、语言等）

4.2 安装 Skill

使用 skills.sh CLI（推荐）

Vercel 构建的 skills.sh 是 Agent Skills 的目录平台：

npx skills add <owner/repo>

系统会引导你完成整个流程。

安装官方技能示例

安装 Flutter 技能：

npx skills add flutter/skills --skill '*' --agent universal

安装 Dart 技能：

npx skills add dart-lang/skills --skill '*' --agent universal

4.3 使用 Skill

安装好 Skill 后，兼容的 AI 智能体会自动发现并使用它们。

如果系统未自动触发，可以直接告诉 LLM 使用特定 Skill：

“使用 [技能名称] 技能，在项目中实现 [具体任务]”

第五章：最佳实践

5.1 Metadata（元信息）设计原则

Metadata 是技能的“说明书 + 合同 + 配置入口”。它回答：

• 这个 Skill 叫什么？解决什么问题？
• 输入/输出是什么结构？成功标准是什么？
• 有哪些风险与边界？

没有 Metadata 的 Agent，通常会变成“写得很好，但不可控”。

5.2 Instruction（指令）设计原则

Instruction 是技能的“操作系统”，应该是可执行的 SOP：

• 先澄清哪些信息，缺什么就问什么
• 什么情况下必须检索，什么情况下不该检索
• 工具如何选择、调用顺序是什么、失败怎么兜底
• 结果如何验证、冲突证据如何处理
• 输出格式、引用规范、口吻要求
• 最终如何自检与验收

5.3 Resources（资源）管理

• scripts/：存放可自动执行的脚本，Agent 直接运行，结果进入上下文
• references/：存放深度参考资料、字段说明、决策表等
• assets/：存放示意图、模板、CSV 等静态资源

5.4 开发要点

• SKILL.md 正文建议不超过 500 行
• 元数据中的 description 要足够明确，确保智能体能准确判断触发时机
• 复杂任务可拆分为多个子技能文档，独立加载
• 遵循最小权限原则，Skill 仅提供操作指引，不能替代运行时环境与权限策略

第六章：高级主题

6.1 Skills 与 MCP 的协同

MCP 提供了原始的机械工具，而 Agent Skills 提供了正确操作这些机械工具的专业知识。两者可以协同工作：Skills 定义“做什么、怎么做”，MCP 负责“调用什么工具”。

6.2 技能的市场与生态

• skills.sh：Vercel 构建的技能目录平台
• 官方仓库：Flutter 团队维护 flutter/skills 和 dart-lang/skills
• 社区贡献：GitHub 上已有大量开源技能可供参考和使用

6.3 安全注意事项

Agent Skills 是快速编写但难以在部署前验证的。需要建立完善的权限模型和安全审查机制，遵循最小权限原则。

B. 术语表

术语	说明
Agent Skills	可复用的能力扩展包，包含指令、脚本和资源
SKILL.md	技能的核心文件，包含元数据和执行指令
渐进式披露	按需加载信息的三级机制
MCP	模型上下文协议，用于工具连接
上下文窗口	LLM 的工作记忆，有 token 限制