深度解析 Agent Skills：从零到一的完全指南
本文将从零开始，深入讲解 Agent Skills 这一开放标准的概念、设计原理、最佳实践和实际应用案例，帮助团队快速上手并高效利用这一强大功能。
适用平台：Cursor IDE、Claude Code、Claude.ai 等支持 Agent Skills 标准的 AI 工具
目录
- 什么是 Agent Skills？
- 为什么需要 Skills？
- Skills 的核心特性
- Skills 的工作原理
- SKILL.md 文件格式详解
- Skills vs Rules vs Commands 的区别
- Skills 最佳实践
- 10 个实战 Skills 案例
- 如何创建自己的 Skill
- 常见问题与反模式
- 参考资源
1. 什么是 Agent Skills？
1.1 定义
Agent Skills 是一种开放标准，用于扩展 AI Agent 的专业能力。简单来说，Skills 是一组指令、脚本和资源的集合，可以让 AI Agent 动态加载以提升特定任务的执行效果。
你可以把 Skills 想象成给 AI 的「入职培训手册」——它们将 Claude 从一个通用助手转变为具备特定领域知识的专业助手。
1.2 核心理念
Skills = 指令 + 脚本 + 资源
一个 Skill 就是一个文件夹，里面包含：
- SKILL.md：主要的指令文件（必需）
- scripts/：可执行的脚本代码（可选）
- references/：参考文档（可选）
- assets/：静态资源文件（可选）
1.3 典型使用场景
| 场景 | 描述 |
|---|---|
| 领域专业知识 | 法律审查流程、数据分析管道、财务报表处理 |
| 新能力扩展 | 创建演示文稿、构建 MCP 服务器、分析数据集 |
| 可重复工作流 | 将多步骤任务转化为一致且可审计的流程 |
| 跨工具互操作 | 在不同支持 Skills 的 Agent 产品间复用同一个 Skill |
2. 为什么需要 Skills？
2.1 AI Agent 的局限性
尽管 AI Agent 能力越来越强，但它们往往缺乏完成真实工作所需的上下文：
- 缺乏程序性知识：不知道你公司的特定工作流程
- 缺乏组织特定信息：不了解你的数据库结构、API 规范
- 效率不高：每次都从零开始理解相同任务
2.2 Skills 的价值
Skills 通过提供按需加载的程序性知识来解决这些问题：
┌─────────────────────────────────────────────────────────────┐
│ 传统方式 │
│ 用户请求 → AI 思考 → 生成通用响应 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 使用 Skills │
│ 用户请求 → 自动识别相关 Skill → 加载专业知识 → 精准执行 │
└─────────────────────────────────────────────────────────────┘
2.3 三方共赢
| 角色 | 收益 |
|---|---|
| Skill 作者 | 一次构建，多处部署 |
| 兼容的 Agent | 用户可以开箱即用地扩展 Agent 能力 |
| 团队和企业 | 将组织知识封装成可移植、版本控制的包 |
3. Skills 的核心特性
3.1 四大特性
┌──────────────┬──────────────────────────────────────────────┐
│ 可移植性 │ 支持 Agent Skills 标准的任何 Agent 都可使用 │
├──────────────┼──────────────────────────────────────────────┤
│ 版本控制 │ 以文件形式存储，可通过 Git 追踪或通过 │
│ │ GitHub 链接安装 │
├──────────────┼──────────────────────────────────────────────┤
│ 可执行性 │ 可包含 Agent 执行的脚本和代码 │
├──────────────┼──────────────────────────────────────────────┤
│ 渐进式加载 │ 按需加载资源，保持上下文使用效率 │
└──────────────┴──────────────────────────────────────────────┘
3.2 兼容性
Agent Skills 是一个开放标准，由 Anthropic 发布并开源，已被多个主流 AI 开发工具采用：
- Cursor IDE - AI 代码编辑器
- Claude Code - Claude 的命令行工具
- Claude.ai - Claude 网页版（付费计划）
- 其他兼容工具 - 任何实现 Agent Skills 标准的 AI Agent
核心优势：你创建的 Skill 可以在所有支持该标准的工具间无缝复用，无需针对不同平台重写。
4. Skills 的工作原理
4.1 发现与加载流程
┌─────────────────────────────────────────────────────────────┐
│ Skill 生命周期 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① 启动时发现 │
│ └─ AI 工具扫描 skill 目录，读取所有 SKILL.md 元数据 │
│ │
│ ② 上下文匹配 │
│ └─ Agent 根据 description 判断是否相关 │
│ │
│ ③ 动态加载 │
│ └─ 相关 Skill 的完整内容被加载到上下文中 │
│ │
│ ④ 执行任务 │
│ └─ Agent 按照 Skill 指令执行，必要时调用脚本 │
│ │
└─────────────────────────────────────────────────────────────┘
4.2 存储位置
Skills 会从以下位置自动加载（不同工具支持的目录可能有所不同）：
| 位置 | 作用范围 | 支持工具 |
|---|---|---|
.cursor/skills/ | 项目级别 | Cursor |
.claude/skills/ | 项目级别 | Claude Code、Cursor |
.codex/skills/ | 项目级别 | Codex、Cursor |
~/.cursor/skills/ | 用户级别（全局） | Cursor |
~/.claude/skills/ | 用户级别（全局） | Claude Code、Cursor |
~/.codex/skills/ | 用户级别（全局） | Codex、Cursor |
提示：为了最大化兼容性，建议使用 .claude/skills/ 目录，因为它被多个工具支持。
4.3 目录结构示例
.cursor/
└── skills/
└── code-review/
├── SKILL.md # 必需 - 主要指令
├── scripts/ # 可选 - 可执行脚本
│ ├── analyze.py
│ └── format.sh
├── references/ # 可选 - 参考文档
│ └── STANDARDS.md
└── assets/ # 可选 - 静态资源
└── template.json
5. SKILL.md 文件格式详解
5.1 基本结构
每个 SKILL.md 文件包含两部分：
- YAML Frontmatter：元数据（必需）
- Markdown Body：指令内容（必需）
---
name: my-skill-name
description: 描述这个 Skill 做什么以及什么时候使用它
---
# My Skill Name
## 指令
详细的步骤说明...
## 示例
具体的使用案例...
5.2 Frontmatter 字段说明
| 字段 | 必需 | 约束 | 说明 |
|---|---|---|---|
name | ✅ | 最多64字符，仅小写字母、数字、连字符 | Skill 的唯一标识符，必须与父目录名匹配 |
description | ✅ | 最多1024字符 | 描述 Skill 功能和使用时机，Agent 用此判断相关性 |
license | ❌ | - | 许可证名称或引用 |
compatibility | ❌ | 最多500字符 | 环境要求说明 |
metadata | ❌ | - | 任意键值对的额外元数据 |
disable-model-invocation | ❌ | true/false | 设为 true 时仅通过 /skill-name 手动调用 |
5.3 Description 编写最佳实践
Description 是 触发 Skill 的关键，Agent 用它来决定何时使用该 Skill。
✅ 好的写法：
description: Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files or when the user mentions PDFs, forms,
or document extraction.
❌ 糟糕的写法：
description: Helps with PDFs.
编写原则：
- 用第三人称：因为 description 会被注入到系统提示中
- 具体且包含触发词：包含所有可能的关键词
- 包含 WHAT 和 WHEN：说明 Skill 做什么以及何时使用
6. Skills vs Rules vs Commands 的区别
| 特性 | Skills | Rules | Commands |
|---|---|---|---|
| 触发方式 | 智能识别 + 手动调用 | 基于文件类型/路径自动应用 | 手动通过 /command 调用 |
| 适用场景 | 复杂工作流、动态上下文 | 代码规范、项目约定 | 简单的快捷操作 |
| 包含资源 | 脚本、引用、资产 | 仅指令文本 | 仅指令文本 |
| 渐进加载 | ✅ 支持 | ❌ 不支持 | ❌ 不支持 |
| 版本控制 | ✅ 文件夹形式 | ✅ 单文件 | ✅ 单文件 |
选择建议：
- 需要动态上下文发现和"如何做"的指令 → Skills
- 需要始终应用的代码规范 → Rules (alwaysApply: true)
- 需要针对特定文件类型的规则 → Rules (with globs)
- 需要快速执行的简单命令 → Commands
7. Skills 最佳实践
7.1 核心原则：精简至上
上下文窗口是公共资源。Skill 与对话历史、其他 Skill、用户请求共享这个空间。
默认假设：AI 已经非常聪明了。 只添加 AI 不知道的内容。
# ✅ 好的写法（简洁）
## PDF 文本提取
使用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
❌ 糟糕的写法（冗长）
PDF 文本提取
PDF（便携式文档格式）文件是一种常见的文件格式，包含文本、图像和其他内容。 要从 PDF 中提取文本，需要使用库。有很多可用的库... （这些 AI 都知道，无需解释）
### 7.2 保持 SKILL.md 在 500 行以内
**原则**：核心信息在 SKILL.md，详细内容在 references/ 中。
```markdown
# PDF 处理
## 快速开始
[核心指令]
## 更多资源
- 完整 API 详情见 [reference.md](reference.md)
- 使用示例见 [examples.md](examples.md)
7.3 渐进式披露
Skills 使用三级加载系统：
┌─────────────────────────────────────────────────────────────┐
│ 第 1 级：元数据（~100 tokens） │
│ └─ name 和 description，启动时对所有 Skill 加载 │
├─────────────────────────────────────────────────────────────┤
│ 第 2 级：指令（< 5000 tokens 推荐） │
│ └─ SKILL.md 主体，Skill 被激活时加载 │
├─────────────────────────────────────────────────────────────┤
│ 第 3 级：资源（按需） │
│ └─ scripts/、references/、assets/ 中的文件 │
└─────────────────────────────────────────────────────────────┘
7.4 设置适当的自由度
| 自由度 | 适用场景 | 示例 |
|---|---|---|
| 高（文本指令） | 多种方法有效、依赖上下文 | 代码审查指南 |
| 中（伪代码/模板） | 有首选模式、允许变化 | 报告生成 |
| 低（特定脚本） | 操作脆弱、需要一致性 | 数据库迁移 |
7.5 常用设计模式
模板模式
## 报告结构
使用此模板：
```markdown
# [分析标题]
## 执行摘要
[一段概述关键发现]
## 关键发现
- 发现 1 及支持数据
- 发现 2 及支持数据
## 建议
1. 具体可行的建议
2. 具体可行的建议
#### 工作流模式
```markdown
## 表单填写工作流
复制此检查清单并跟踪进度：
任务进度：
- 步骤 1：分析表单
- 步骤 2：创建字段映射
- 步骤 3：验证映射
- 步骤 4：填写表单
- 步骤 5：验证输出
**步骤 1：分析表单**
运行：`python scripts/analyze_form.py input.pdf`
反馈循环模式
## 文档编辑流程
1. 进行编辑
2. **立即验证**：`python scripts/validate.py output/`
3. 如果验证失败：
- 查看错误信息
- 修复问题
- 再次运行验证
4. **只有验证通过后才继续**
8. 10 个实战 Skills 案例
我在 skills-examples/ 目录下准备了 10 个实用的 Skills 示例：
| # | Skill 名称 | 用途 |
|---|---|---|
| 1 | code-review | 代码审查，遵循团队标准 |
| 2 | git-commit-helper | 生成规范的 Git 提交信息 |
| 3 | api-documentation | 自动生成 API 文档 |
| 4 | test-generator | 为代码生成单元测试 |
| 5 | frontend-design | 创建高质量前端界面 |
| 6 | mcp-builder | 构建 MCP 服务器 |
| 7 | webapp-testing | Web 应用自动化测试 |
| 8 | internal-comms | 编写内部沟通文档 |
| 9 | database-migration | 数据库迁移操作指南 |
| 10 | deploy-app | 应用部署自动化 |
每个 Skill 都包含完整的 SKILL.md 文件，可以直接复制到你的项目中使用。
私我获取
9. 如何创建自己的 Skill
9.1 创建流程
┌─────────────────────────────────────────────────────────────┐
│ Skill 创建五步法 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① 理解需求 │
│ └─ 收集具体使用示例，明确 Skill 要解决什么问题 │
│ │
│ ② 规划内容 │
│ └─ 识别需要的脚本、参考文档和资产 │
│ │
│ ③ 创建目录结构 │
│ └─ 建立 skill-name/ 文件夹和 SKILL.md │
│ │
│ ④ 编写内容 │
│ └─ 填写元数据和指令，添加必要资源 │
│ │
│ ⑤ 测试与迭代 │
│ └─ 实际使用，根据效果优化 │
│ │
└─────────────────────────────────────────────────────────────┘
9.2 快速开始模板
# 创建 Skill 目录（使用 .claude 目录以获得更好的兼容性）
mkdir -p .claude/skills/my-skill
# 创建 SKILL.md
cat > .claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 清晰描述这个 Skill 做什么以及什么时候使用它。
---
# My Skill
## 概述
简要说明这个 Skill 的用途。
## 使用指南
### 步骤 1
具体操作说明...
### 步骤 2
具体操作说明...
## 示例
展示实际使用案例...
EOF
10. 常见问题与反模式
10.1 反模式：Windows 路径
# ❌ 避免
scripts\helper.py
# ✅ 使用
scripts/helper.py
10.2 反模式：选项过多
# ❌ 避免 - 令人困惑
"你可以使用 pypdf，或者 pdfplumber，或者 PyMuPDF，或者..."
# ✅ 使用 - 提供默认选项和逃生舱
"使用 pdfplumber 进行文本提取。
对于需要 OCR 的扫描 PDF，改用 pdf2image 配合 pytesseract。"
10.3 反模式：时间敏感信息
# ❌ 避免 - 会过时
"如果你在 2025 年 8 月之前做这个，使用旧 API。"
# ✅ 使用 - 使用「旧模式」部分
## 当前方法
使用 v2 API 端点。
## 旧模式（已弃用）
<details>
<summary>Legacy v1 API</summary>
...
</details>
10.4 反模式：术语不一致
在整个 Skill 中选择一个术语并坚持使用：
- ✅ 始终使用 "API 端点"（不要混用 "URL"、"路由"、"路径"）
- ✅ 始终使用 "字段"（不要混用 "框"、"元素"、"控件"）
10.5 反模式：模糊的 Skill 名称
# ❌ 避免
helper, utils, tools
# ✅ 使用
processing-pdfs, analyzing-spreadsheets, code-review
11. 参考资源
11.1 官方文档
11.2 官方 Skills 仓库
- Anthropic Skills 仓库 - 58,600+ stars
- 包含创意设计、开发技术、企业沟通等多种 Skill 示例
11.3 社区资源
- awesome-cursorrules - 37,500+ stars
- 大量 .cursorrules 配置文件集合
- cursor-skills
- Cursor IDE 最佳实践和指南
11.4 相关工具
- CursorDirectory - Cursor 规则目录
- CursorList - Cursor 资源列表
总结
Agent Skills 是一个由 Anthropic 发布的开放标准，它：
- 标准化了 AI Agent 的能力扩展方式 - 统一的 SKILL.md 格式
- 支持版本控制和团队协作 - 文件夹形式，可纳入 Git 管理
- 通过渐进式加载优化上下文使用 - 按需加载，高效利用 token
- 跨多个 AI 工具可移植 - Cursor、Claude Code、Claude.ai 等均支持
掌握 Skills 的关键在于：
- 📝 写好 Description：这是触发的关键
- 🎯 精简内容：只包含 AI 不知道的信息
- 📂 合理组织：利用 scripts/、references/、assets/
- 🔄 持续迭代：根据实际使用效果优化
希望这篇文章能帮助你和你的团队快速上手 Agent Skills，提升 AI 辅助开发效率！
最后更新：2026年1月
参考来源：
