Agent Skills 完全学习指南：从原理到实战

一、概念与整体认识

1.1 什么是 Agent Skills

Agent Skills（智能体技能）是一种模块化的、可复用的指令包，它给 AI Agent 赋予在特定任务上的专业能力。

用一句话概括：

Skill 是一组经过结构化封装的指令、工作流、脚本和参考资料，Agent 在需要时按需加载，用完即卸，让通用模型变成特定领域的专家。

打个比方：一个大模型就像一位聪明但刚入职的新人——它什么都懂一点，但不熟悉你公司的流程、工具和规范。Skill 就是你给它的操作手册：告诉它"做这类任务时，按这个流程来，用这个工具，输出这个格式"。

与你平时在对话开头写的 System Prompt 不同，Skill 具备以下关键特征：

特征	System Prompt	Agent Skill
复用性	需要每次对话手动粘贴	创建一次，自动按需加载
模块化	所有指令堆在一起	一个 Skill 解决一类问题
渐进加载	全部占用上下文窗口	仅在触发时加载，节省 token
可组合	难以拆分和组合	多个 Skill 自由搭配
可维护	修改一处可能影响其他	独立版本控制、独立测试

1.2 Skill 在 Agent 架构中的位置

要理解 Skill 的角色，先看一个典型 AI Agent 的工作架构：

用户指令
    │
    ▼
┌─────────────────────────────────────┐
│         Agent 核心（LLM 大脑）        │
│                                      │
│  ┌──────────┐  ┌──────────┐         │
│  │  感知层   │  │  规划层   │         │
│  │(理解意图) │  │(制定计划) │         │
│  └──────────┘  └──────────┘         │
│  ┌──────────┐  ┌──────────┐         │
│  │  执行层   │  │  记忆层   │         │
│  │(调用工具) │  │(上下文)   │         │
│  └──────────┘  └──────────┘         │
│                                      │
│  ┌──────────────────────────────┐   │
│  │     ★ Skills（技能层）★       │   │
│  │  为 Agent 提供领域知识和流程   │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
    │           │           │
    ▼           ▼           ▼
 ┌──────┐  ┌──────┐  ┌──────────┐
 │ 工具  │  │ MCP  │  │ 外部 API │
 │(Tool) │  │ 服务 │  │  / 数据  │
 └──────┘  └──────┘  └──────────┘

各层级的关系可以这样理解：

LLM 模型：Agent 的"大脑"，负责理解、推理和生成
Tools（工具）：Agent 的"手脚"，执行具体操作（如搜索网页、运行代码、读写文件）
MCP（模型上下文协议）：连接外部系统的"管道"，让 Agent 能访问数据库、API 等
Memory（记忆）：Agent 的"经验库"，存储对话历史和事实
Skills（技能）：Agent 的"操作手册"，提供流程知识和领域最佳实践

关键区分：Tools 提供执行能力（"能做什么"），Skills 提供流程知识（"该怎么做"）。一个发票处理 Skill 会指导 Agent 使用 PDF 提取工具——但 Skill 提供的是判断逻辑：提取哪些字段、如何校验、输出什么格式。

1.3 适用场景示例

Agent Skills 适合以下场景：

场景	Skill 做什么	搭配的 Tool
数据库查询	定义查询规范、结果格式、安全校验规则	SQL 执行工具
调用外部 API	定义 API 调用策略、错误重试逻辑、响应解析规则	HTTP 请求工具
文档处理	定义提取字段、校验规则、输出模板	PDF/Word 解析工具
代码审查	定义审查清单、安全检查项、代码规范	代码执行/静态分析工具
合规审核	定义审核框架、法规对照表、严重程度分级	搜索/文档检索工具
客户支持	定义分诊逻辑、工单格式、升级标准	工单系统 API 工具
报告生成	定义报告结构、图表类型、数据分析方法	图表渲染/数据分析工具

一条判断规则：如果你发现自己在每次对话中反复粘贴同一段提示词来指导 Agent 做某类任务——那就是一个 Skill 在等你把它写出来。

二、原理与工作机制

2.1 Skill 的基本组成要素

一个标准的 Skill 就是一个文件夹，核心是一个 SKILL.md 文件：

my-skill/
├── SKILL.md              # 必需：元数据 + 指令（核心文件）
├── scripts/              # 可选：可执行脚本
│   ├── validate.py
│   └── transform.sh
├── references/           # 可选：参考文档
│   ├── api-spec.md
│   └── schema.yaml
└── assets/               # 可选：模板和资源
    └── output-template.json

SKILL.md 的结构由两部分组成：

第一部分：YAML Frontmatter（元数据）

yaml

---
name: invoice-processor
description: >
  从 PDF 发票中提取结构化数据，校验金额并输出 JSON 格式。
  当用户上传或提及发票、账单文件时使用此技能。
---

字段	说明	要求
`name`	技能名称	必填，≤64 字符，小写字母+数字+连字符
`description`	技能描述和触发条件	必填，≤1024 字符，需要说明"做什么"和"什么时候用"

第二部分：Markdown 正文（指令）

markdown

# 发票处理技能

## 处理步骤

1. 使用 pdfplumber 打开 PDF 文件
2. 提取表头信息：发票号、日期、供应商名称
3. 提取行项目：品名、数量、单价、金额
4. 校验：行项目金额合计 = 发票总额
5. 输出标准 JSON 格式

## 校验规则

- 金额精度保留 2 位小数
- 日期格式统一为 ISO 8601
- 缺失必填字段时，标记为 "MISSING" 并告知用户

## 输出格式

参见 `assets/output-template.json`

## 注意事项

- 扫描件发票需要先 OCR，使用 pdf2image + pytesseract
- 多币种发票需标注原始币种，不做汇率转换

各组成部分的职责：

组成	作用	何时加载
YAML 元数据	告诉 Agent "我是谁、什么时候该用我"	启动时（约 50-100 tokens）
Markdown 正文	告诉 Agent "具体怎么做"	被触发时（通常 < 5000 tokens）
scripts/	提供确定性操作（校验、格式转换）	指令中引用时，按需执行
references/	提供参考文档（API 文档、数据 schema）	指令中引用时，按需读取
assets/	提供模板和资源文件	指令中引用时，按需读取

2.2 Agent 如何决定何时调用 Skill

Agent 选择 Skill 的过程可以分为三步：

第 1 步：意图识别

用户发出指令后，Agent 分析请求的语义意图。例如：

用户说："帮我处理这份发票" → 意图：发票处理
用户说："检查这段代码有没有安全问题" → 意图：代码安全审查

第 2 步：技能匹配

Agent 将用户意图与所有已注册 Skill 的 description 进行匹配。这就是为什么 description 如此重要——它是 Agent 做匹配决策的唯一依据。

用户意图: "处理这份发票"
    │
    ├─ invoice-processor: "从 PDF 发票中提取数据..." ✅ 强匹配
    ├─ code-reviewer: "审查代码安全性..."           ✗ 不匹配
    └─ report-generator: "生成数据分析报告..."       ✗ 不匹配

第 3 步：参数填充

Agent 从用户输入和上下文中提取 Skill 所需的输入参数（如文件路径、配置选项等），然后触发 Skill。

2.3 Skill 调用的生命周期

一个完整的 Skill 调用链路如下：

[1] 启动阶段
    Agent 启动 → 扫描所有可用 Skill → 加载每个 Skill 的 name + description
    （此时每个 Skill 仅占用约 50-100 tokens）

[2] 用户请求
    用户: "帮我处理附件中的发票，提取关键字段"

[3] 意图匹配
    Agent 对比所有 Skill 的 description → 命中 invoice-processor

[4] 技能加载
    Agent 通过文件系统读取 SKILL.md 完整内容 → 指令进入上下文窗口
    （此时约增加 1000-5000 tokens）

[5] 执行阶段
    Agent 按指令逐步执行：
    ├─ 调用 PDF 解析工具提取文本
    ├─ 读取 references/schema.yaml 确认字段规范
    ├─ 运行 scripts/validate.py 校验数据
    └─ 按 assets/output-template.json 输出结果

[6] 返回结果
    Agent 将处理结果返回用户，附带校验报告

[7] 清理
    Skill 指令从活跃上下文中退出，释放 token 空间

这种"按需加载、用完释放"的模式叫做渐进式加载（Progressive Disclosure），是 Agent Skills 架构的核心设计。它解决了一个关键问题：如果一个 Agent 有 100 个 Skill，每个 Skill 的指令都常驻上下文，context window 会被瞬间塞满。通过渐进式加载，100 个 Skill 在启动时仅消耗约 5000-10000 tokens（只加载元数据），而一次任务通常只激活 1-2 个 Skill。

三、Skill 设计规范

3.1 如何定义清晰的职责边界

核心原则：一个 Skill 做好一件事。

这和编程中的"单一职责原则"一样——一个 Skill 应该覆盖一个内聚的任务领域，既不要太窄（导致简单任务需要加载多个 Skill），也不要太宽（导致 Skill 变成万能但什么都做不好的"巨型 prompt"）。

判断标准：

范围	信号	建议
太窄	一个简单任务需要 3+ 个 Skill 配合	合并相关 Skill
恰当	一个 Skill 覆盖一类完整任务	保持现状
太宽	Skill 超过 500 行，内部指令互相矛盾	拆分为多个 Skill

好的边界示例：

✅ "查询数据库 + 格式化结果"——一个内聚的任务单元
❌ "查询数据库 + 格式化结果 + 数据库运维管理"——后者应该独立为另一个 Skill

3.2 如何设计输入输出参数

Skill 的输入输出不像函数那样有强类型签名，而是通过自然语言在指令中描述。关键是让模型一眼就知道需要什么、会得到什么。

输入设计原则：

明确列出必需输入：在指令中清楚说明"此 Skill 需要用户提供 XX"
定义缺失输入的处理策略：是报错、用默认值、还是反问用户
给出输入示例：模型对具体样例的理解远优于抽象描述

输出设计原则：

提供输出模板：使用代码块展示期望的输出格式
明确必填/可选字段：哪些字段必须有值，哪些可以为空
定义边界情况：空数据、异常数据时输出什么

markdown

## 输入要求

- **必须**：PDF 格式的发票文件（用户上传或提供路径）
- **可选**：指定输出币种（默认保留原始币种）
- 如果用户未提供文件，请询问用户上传

## 输出格式

```json
{
  "invoice_number": "INV-2026-001",
  "date": "2026-04-19",
  "vendor": "示例供应商",
  "items": [
    { "name": "商品A", "quantity": 2, "unit_price": 100.00, "amount": 200.00 }
  ],
  "total": 200.00,
  "currency": "CNY",
  "validation": { "status": "passed", "errors": [] }
}


### 3.3 命名与描述的最佳实践

**name 的命名规则**：

- 使用小写字母 + 数字 + 连字符（如 `invoice-processor`、`code-review-security`）
- 名称应当自描述，看名字就知道做什么
- 避免太泛的名字（如 `helper`、`utils`）

**description 是最重要的字段**——它直接决定 Skill 能否被正确触发。

**写好 description 的公式**：

[做什么] + [什么时候用] + [不适用的情况（可选）]


| 质量 | 示例 |
|------|------|
| ❌ 太模糊 | `处理文档` |
| ❌ 太宽泛 | `处理各种类型的文件和数据` |
| ✅ 精准 | `从 PDF 发票中提取行项目、校验金额并输出 JSON。当用户上传发票或提及账单处理时使用。不用于合同或一般性 PDF 阅读。` |

> **经验法则**：如果你的 Skill 没有被正确触发，90% 的情况不是指令有问题，而是 description 写得不够精准。

### 3.4 错误处理与超时/重试建议

在 Skill 指令中显式定义错误处理策略：

```markdown
## 错误处理

### 文件无法解析
- 首先尝试 OCR 方式（pdf2image + pytesseract）
- 如果 OCR 也失败，告知用户"文件可能已损坏或加密，请重新上传"

### 数据校验失败
- 列出所有校验错误项
- 不要自行修正数据，将错误报告给用户确认

### 外部 API 超时
- 最多重试 2 次，间隔 3 秒
- 3 次仍失败时，返回已完成的部分结果并告知用户

四、实战：从零创建一个完整的 Skill

本节以一个具体场景——"查询天气并给出穿衣建议"——完整演示 Skill 的创建过程。

4.1 需求分析

要解决的问题：用户告诉 Agent 一个城市名称，Agent 查询该城市天气，并根据温度、天气状况给出穿衣建议。

为什么需要 Skill：

通用模型不知道你的穿衣建议标准（比如公司团建的着装要求、或者你个人的体质偏好）
每次都要告诉 Agent "低于 10 度建议穿羽绒服、10-20 度穿外套…" 很烦
输出格式希望统一，方便后续处理

4.2 接口与函数设计

输入参数：

参数	类型	是否必填	说明
city	string	是	城市名称（中文或英文均可）
date	string	否	查询日期，ISO 8601 格式，默认今天
scene	string	否	使用场景（如 `日常`、`商务`、`户外运动`），默认 `日常`

输出结构：

json

{
  "city": "北京",
  "date": "2026-04-19",
  "weather": {
    "condition": "晴",
    "temp_high": 26,
    "temp_low": 12,
    "humidity": 35,
    "wind": "北风 3-4 级"
  },
  "clothing_advice": {
    "scene": "日常",
    "suggestion": "白天温暖，建议穿薄外套或卫衣；早晚温差大，外出请多带一件外套。",
    "items": ["薄外套/卫衣", "长裤", "运动鞋"]
  }
}

4.3 Skill 定义：完整的 SKILL.md

下面是完整的 Skill 目录结构：

weather-clothing-advisor/
├── SKILL.md
├── scripts/
│   └── format_output.py
└── references/
    └── clothing-rules.md

SKILL.md：

markdown

---
name: weather-clothing-advisor
description: >
  查询指定城市天气并根据温度、天气状况和场景给出穿衣建议。
  当用户询问某个城市的天气或穿什么衣服时使用此技能。
  不适用于天气历史数据分析或气象科学问题。
---

# 天气查询与穿衣建议

## 处理流程

1. **获取用户输入**
   - 必须：城市名称
   - 可选：日期（默认今天）、场景（默认"日常"）
   - 如果用户未指定城市，请礼貌地询问

2. **查询天气数据**
   - 使用网络搜索工具查询"[城市名] [日期] 天气预报"
   - 提取以下信息：天气状况、最高温、最低温、湿度、风力
   - 如果查询失败，告知用户并建议稍后重试

3. **生成穿衣建议**
   - 根据 `references/clothing-rules.md` 中的规则匹配温度区间
   - 根据用户指定的 scene（场景）调整建议
   - 特别关注：雨天需提醒带伞，大风天避免宽松外套

4. **格式化输出**
   - 按照下方 JSON 格式输出结果
   - 同时生成一段简洁友好的自然语言摘要

## 输出格式

```json
{
  "city": "城市名",
  "date": "YYYY-MM-DD",
  "weather": {
    "condition": "天气状况",
    "temp_high": 最高温,
    "temp_low": 最低温,
    "humidity": 湿度百分比,
    "wind": "风向风力"
  },
  "clothing_advice": {
    "scene": "场景",
    "suggestion": "一段穿衣建议文字",
    "items": ["建议穿着单品1", "建议穿着单品2"]
  }
}

注意事项

温度单位统一使用摄氏度（℃）
如果目标城市有特殊天气预警（台风、暴雪等），在建议中优先提醒安全
商务场景下，建议偏正式着装；户外运动场景下，注重功能性和舒适度


**references/clothing-rules.md**：

```markdown
# 穿衣建议温度规则

## 温度区间对照表

| 温度区间 | 日常场景 | 商务场景 | 户外运动场景 |
|---------|---------|---------|-------------|
| ≥ 30℃ | 短袖T恤、短裤/裙、凉鞋 | 短袖衬衫、轻薄西裤 | 速干T恤、运动短裤、遮阳帽 |
| 20-29℃ | 长袖/薄外套、长裤 | 衬衫、轻薄西装外套 | 运动长袖、运动裤 |
| 10-19℃ | 厚外套/毛衣、长裤 | 西装三件套、风衣 | 抓绒衣、冲锋衣、运动裤 |
| 0-9℃ | 羽绒服/棉服、保暖内衣 | 大衣、羊毛衫、围巾 | 专业保暖层、防风外套 |
| < 0℃ | 厚羽绒服、帽子手套围巾 | 厚大衣、保暖配件齐全 | 专业防寒装备、保暖配件 |

## 特殊天气修正

- **雨天**：无论温度，提醒携带雨伞；建议防水鞋或靴子
- **大风（≥5级）**：避免宽松裙装和大帽子；商务场景注意领带固定
- **雾霾**：建议佩戴口罩
- **紫外线强**：建议防晒、太阳镜、遮阳帽

4.4 与 Agent 集成

Skill 写好后，需要让 Agent 能发现它。不同平台的安装方式如下：

Claude Code（文件系统方式）：

bash

# 个人级别（所有项目可用）
mkdir -p ~/.claude/skills/
cp -r weather-clothing-advisor/ ~/.claude/skills/

# 项目级别（仅当前项目可用，可通过 Git 共享给团队）
mkdir -p .claude/skills/
cp -r weather-clothing-advisor/ .claude/skills/

Claude API（通过 API 上传）：

bash

# 将 Skill 目录打包为 ZIP
zip -r weather-clothing-advisor.zip weather-clothing-advisor/

# 通过 Skills API 上传（需要 API Key）
curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@weather-clothing-advisor.zip"

Claude.ai（设置页面上传）：

将 Skill 文件夹打包为 ZIP
进入 Claude.ai → Settings → Features
上传 ZIP 文件

安装完成后，Agent 在下次启动时会自动扫描并注册该 Skill。

4.5 调用示例

场景：用户查询北京天气

用户输入：

明天去北京出差，穿什么衣服合适？

Agent 内部处理流程：

[1] 意图识别
    → 用户想知道北京的天气和穿衣建议
    → 匹配到 weather-clothing-advisor（description 命中"穿什么衣服"）

[2] 参数提取
    → city: 北京
    → date: 明天（2026-04-20）
    → scene: 商务（从"出差"推断）

[3] 加载 Skill
    → 读取 SKILL.md 完整指令到上下文

[4] 执行步骤
    → 搜索"北京 2026-04-20 天气预报"
    → 获取结果：晴，22/11℃，北风3级，湿度30%
    → 读取 references/clothing-rules.md
    → 匹配温度区间 10-19℃（按最低温）+ 商务场景

[5] 生成结果

Agent 最终回复：

明天北京天气晴好，气温 11-22℃，北风 3 级。

**穿衣建议（商务出差）**：

白天气温舒适，建议穿衬衫搭配轻薄西装外套；早晚温差大（最低 11℃），
建议另备一件风衣或厚外套，以应对早晚通勤。

推荐穿着：
- 衬衫 + 西装外套（白天）
- 风衣（早晚备用）
- 西裤
- 皮鞋

{
  "city": "北京",
  "date": "2026-04-20",
  "weather": {
    "condition": "晴",
    "temp_high": 22,
    "temp_low": 11,
    "humidity": 30,
    "wind": "北风 3 级"
  },
  "clothing_advice": {
    "scene": "商务",
    "suggestion": "白天温度舒适可穿衬衫搭配轻薄西装外套，早晚温差大建议备风衣。",
    "items": ["衬衫", "西装外套", "风衣（早晚备用）", "西裤", "皮鞋"]
  }
}

五、调试与优化

5.1 如何验证 Skill 是否被正确调用

方法 1：观察 Agent 行为

直接在对话中发出应该触发 Skill 的请求，观察 Agent 是否按照 Skill 指令中的步骤执行。如果 Agent 的回复明显缺少 Skill 指令中要求的格式或步骤，说明 Skill 未被触发。

方法 2：查看执行日志

在 Claude Code 中，Agent 读取 Skill 文件时会通过 bash 命令执行，可以在执行记录中看到类似以下操作：

bash

cat ~/.claude/skills/weather-clothing-advisor/SKILL.md

如果看到这条命令，说明 Skill 已被成功触发。

方法 3：直接询问 Agent

你可以在对话中直接问：

你现在有哪些可用的 Skills？处理我的上一个请求时，你使用了哪个 Skill？

5.2 常见问题与排查思路

问题	可能原因	排查方法
Skill 不触发	description 与用户意图不匹配	检查 description 是否涵盖用户常用的表述方式
Skill 被错误触发	description 太宽泛，与其他 Skill 重叠	缩小 description 范围，添加"不适用于…"的排除说明
参数填错	指令中对输入描述不够清晰	在指令中添加更具体的参数示例和约束条件
输出格式不稳定	只用文字描述了格式，没有提供模板	添加具体的输出模板（JSON/表格示例）
Skill 加载但执行不完整	指令太长，模型注意力分散	精简指令，将详细内容移入 references/ 文件
辅助文件未被读取	指令中未明确说明何时读取	添加明确的条件触发语句，如"当遇到 X 情况时，读取 references/Y.md"

5.3 优化 Skill 的方向

方向 1：提升描述精准度

yaml

# 优化前
description: 处理天气相关的问题

# 优化后
description: >
  查询指定城市的实时天气并给出穿衣建议。
  当用户询问某城市的天气、温度、穿什么衣服时使用。
  不适用于气象数据分析、历史天气查询或天气预警订阅。

方向 2：优化参数粒度

将模糊的输入要求变为明确的参数定义：

markdown

# 优化前
需要用户告诉你一些关于任务的信息。

# 优化后
## 输入参数
- **city**（必填）：城市名称，支持中文或英文
- **date**（可选）：查询日期，格式 YYYY-MM-DD，默认今天
- **scene**（可选）：场景类型，可选值：日常 | 商务 | 户外运动，默认"日常"
- 如果用户未提供 city，请反问："请问您想查询哪个城市的天气？"

方向 3：添加 Gotchas（已知坑点）

在 Skill 使用过程中，每遇到一次 Agent 犯错，就把纠正记录添加到 Gotchas 部分：

markdown

## 已知坑点（Gotchas）

- 搜索"广州天气"时可能返回广州市或广州区的结果，需确认是哪个广州
- 温度建议应以最低温为主要参考（人体对寒冷比对炎热更敏感）
- 如果天气数据来源返回华氏度，需先转换为摄氏度再匹配规则

方向 4：添加安全校验

markdown

## 安全检查

- 不要在输出中包含用户的精确位置信息（如 GPS 坐标）
- 如果用户请求的城市不存在或无法识别，不要猜测，直接告知无法查询
- 天气数据仅供参考，在极端天气情况下，建议用户关注官方气象预警

六、进阶与扩展

6.1 组织多个 Skills 形成工作流

当一个复杂任务需要多个 Skill 协作时，有两种组织方式：

方式 A：顺序编排——在一个主 Skill 中引用其他 Skill

markdown

# 出差准备助手

## 工作流

1. 首先使用 `weather-clothing-advisor` 技能查询目的地天气和穿衣建议
2. 然后使用 `travel-checklist` 技能生成出差物品清单
3. 最后使用 `meeting-briefing` 技能准备会议资料摘要
4. 将以上信息汇总为一份"出差准备报告"

方式 B：松耦合——让 Agent 自主选择组合

将每个 Skill 设计为独立模块，通过精确的 description 让 Agent 自行判断何时需要调用哪个。这种方式更灵活，但需要 description 足够精准以避免遗漏或误触发。

6.2 设计可复用、可组合的 Skills

策略 1：分层设计

通用层：data-formatter（通用数据格式化）
         ↑
领域层：invoice-formatter（发票专用格式化，继承通用层并添加发票特有规则）

策略 2：输出标准化

让同一类 Skill 的输出格式保持一致，使得下游 Skill 可以无缝接收上游 Skill 的输出：

weather-advisor 输出 → 标准 JSON → travel-planner 接收
finance-analyzer 输出 → 标准 JSON → report-generator 接收

6.3 权限与安全注意事项

注意点	说明
最小权限原则	一个处理文档的 Skill 不需要网络访问权限；一个查询 API 的 Skill 不需要文件系统写入权限
密钥管理	永远不要把 API Key、密码等敏感信息硬编码在 SKILL.md 或脚本中；使用环境变量或安全存储
来源审计	只使用你自己编写或来自可信来源（如官方仓库）的 Skill；社区 Skill 需要完整审查后再使用
定期审查	每个 Skill 应有明确的负责人和审查周期；过时的 Skill 会给出错误建议
供应链安全	安全审计发现 36.82% 的社区公开 Skill 存在安全缺陷——对待 Skill 要像对待代码依赖一样谨慎

七、总结与实践建议

要点总结

Agent Skills 是什么：一个模块化的指令包，让通用 Agent 获得特定领域的专家能力。核心载体是 SKILL.md 文件，包含元数据（name + description）和 Markdown 格式的操作指令。
如何设计一个好的 Skill：
- 一个 Skill 做一件事：职责边界清晰，不求大而全
- description 是灵魂：精准描述"做什么 + 什么时候用 + 什么时候不用"
- 指令要具体：步骤化、有模板、有示例，不要假设模型会自己推断
- 善用辅助文件：大段参考资料放 references/，确定性逻辑放 scripts/
- 持续迭代：根据实际执行效果不断完善 Gotchas 和指令细节
落地最重要的五个注意事项：
- 先测量再优化：部署前建立 baseline，部署后对比效果
- description 优先调优：Skill 不触发时，先改 description 而非指令
- 控制指令长度：SKILL.md 正文建议在 500 行 / 5000 tokens 以内
- 版本控制：像管理代码一样管理 Skill，用 Git 追踪每次变更
- 安全第一：不使用未经审查的第三方 Skill，不在 Skill 中硬编码敏感信息

练习题

练习 1：设计一个"代码审查"Skill

场景：你的团队有一套代码审查标准，包括命名规范、安全检查项（禁止 eval()、SQL 必须参数化）、测试覆盖率要求（≥80%），以及输出格式（Markdown 表格列出问题清单）。
请设计这个 Skill 的完整 SKILL.md，包括：元数据、处理步骤、审查清单、输出模板和至少 3 条 Gotchas。

练习 2：设计一组可组合的"数据分析报告"Skill

场景：你需要三个 Skill 协作完成月度数据报告——一个负责从数据库提取数据、一个负责生成图表、一个负责汇总撰写报告。
请设计这三个 Skill 的 name、description 和输入输出接口，确保它们之间可以通过标准化的 JSON 格式无缝传递数据。思考：如何避免三个 Skill 的 description 互相重叠导致误触发？

Agent Skills 完全学习指南：从原理到实战 ​

一、概念与整体认识 ​

1.1 什么是 Agent Skills ​

1.2 Skill 在 Agent 架构中的位置 ​

1.3 适用场景示例 ​

二、原理与工作机制 ​

2.1 Skill 的基本组成要素 ​

2.2 Agent 如何决定何时调用 Skill ​

2.3 Skill 调用的生命周期 ​

三、Skill 设计规范 ​

3.1 如何定义清晰的职责边界 ​

3.2 如何设计输入输出参数 ​

四、实战：从零创建一个完整的 Skill ​

4.1 需求分析 ​

4.2 接口与函数设计 ​

4.3 Skill 定义：完整的 SKILL.md ​

注意事项 ​

4.4 与 Agent 集成 ​

4.5 调用示例 ​

五、调试与优化 ​

5.1 如何验证 Skill 是否被正确调用 ​

5.2 常见问题与排查思路 ​

5.3 优化 Skill 的方向 ​

六、进阶与扩展 ​

6.1 组织多个 Skills 形成工作流 ​

6.2 设计可复用、可组合的 Skills ​

6.3 权限与安全注意事项 ​

七、总结与实践建议 ​

要点总结 ​

练习题 ​

Agent Skills 完全学习指南：从原理到实战

一、概念与整体认识

1.1 什么是 Agent Skills

1.2 Skill 在 Agent 架构中的位置

1.3 适用场景示例

二、原理与工作机制

2.1 Skill 的基本组成要素

2.2 Agent 如何决定何时调用 Skill

2.3 Skill 调用的生命周期

三、Skill 设计规范

3.1 如何定义清晰的职责边界

3.2 如何设计输入输出参数

四、实战：从零创建一个完整的 Skill

4.1 需求分析

4.2 接口与函数设计

4.3 Skill 定义：完整的 SKILL.md

注意事项

4.4 与 Agent 集成

4.5 调用示例

五、调试与优化

5.1 如何验证 Skill 是否被正确调用

5.2 常见问题与排查思路

5.3 优化 Skill 的方向

六、进阶与扩展

6.1 组织多个 Skills 形成工作流

6.2 设计可复用、可组合的 Skills

6.3 权限与安全注意事项

七、总结与实践建议

要点总结

练习题