Agent Skill是什么?创建和设计高质量Agent Skill的完整教学

一、什么是 Skill？为什么需要 Skill？

1.1 Skill 的本质

Skill 本质上是一种模块化、可独立运行的能力扩展单元，作用就在于借助

，把 AI Agent 的能力往前再推一步。把它理解成 AI Agent 的「岗位培训手册」会更直观：原本偏通用的 AI，经过这套能力封装之后，就能转变为掌握特定领域 procedural knowledge（程序性知识）的专业 Agent。

大模型本身拥有海量的常识性知识，但在以下场景中往往力不从心：

• 公司内部知识
  ：内部系统、业务流程、数据 schema、合规规范

• 重复性工作流
  ：每次都要从零推理，效率低且不一致

• 工具与格式集成
  ：特定 API、文件格式、模板的使用细节

• 领域最佳实践
  ：经过验证的操作步骤、判断标准、避坑指南

Skill 的价值，就是把这些「模型不知道、但执行任务必须知道」的知识，以结构化的方式打包，让 Agent 在需要时能精准调用。

1.2 一个「好用的 Skill」长什么样？

判断一个 Skill 好不好用，核心看三点：

维度	好的 Skill	差的 Skill
触发准确性	用户一提相关需求就被正确调用，不误触发、不漏触发	描述模糊，该触发时不触发，不该触发时乱触发
执行有效性	按 Skill 指引能稳定产出高质量结果	看完还是不知道怎么做，产出质量全靠运气
上下文效率	只在需要时加载必要信息，不浪费 token	不管用不用都塞一大堆内容，上下文臃肿

二、Skill 设计的核心原则

2.1 原则一：简洁至上（Concise is Key）

上下文窗口是公共资源。Skill 会和系统提示词、对话历史、其他 Skill 的元信息、用户实际请求一起竞争有限的上下文空间。

只添加 AI Agent 真正不知道的上下文。每一段信息都要经受拷问：「AI 真的需要这段解释吗？」「这几段话值得它消耗的 token 吗？」

• 能用一句话说清的，不用一段话
• 优先用简洁示例代替冗长解释
• 常识性内容一律删掉
• 详细内容放到 references 目录，按需加载

2.2 原则二：自由度匹配（Set Appropriate Degrees of Freedom）

Skill 的指令具体程度，应该和任务的「脆弱度」和「可变度」匹配：

自由度等级	形式	适用场景
高自由度	纯文字指令、启发式指引	多种方法都可行、决策依赖上下文、靠经验判断
中自由度	伪代码 / 带参数的脚本	有推荐模式、允许一定变化、配置影响行为
低自由度	具体脚本、少量参数	操作脆弱易出错、一致性至关重要、必须按固定顺序

：把 AI Agent 想象成在探索一条路——窄桥两边是悬崖，就需要具体的护栏（低自由度）；开阔的原野，可以走很多条路（高自由度）。

2.3 原则三：渐进式披露（Progressive Disclosure）

Skill 采用三级加载机制来高效管理上下文：

Level 1: 元信息（name + description）→ 始终在上下文中（约 100 字）
Level 2: SKILL.md 正文              → Skill 触发后才加载（< 5000 字）
Level 3: 捆绑资源（scripts/references/assets）→ Agent 按需加载（理论无上限）

：SKILL.md 正文保持精简，控制在 500 行以内。接近上限时，把内容拆分到独立文件中。

# PDF 处理
## 快速上手
用 pdfplumber 提取文本：[代码示例]

## 高级功能
- **表单填充**：详见 [FORMS.md](references/FORMS.md)
- **API 参考**：详见 [REFERENCE.md](references/REFERENCE.md)
- **示例**：详见 [EXAMPLES.md](references/EXAMPLES.md)

Agent 只在需要时才加载对应的参考文件。

bigquery-skill/
├── SKILL.md              # 概览和导航
└── references/
    ├── finance.md        # 收入、计费指标
    ├── sales.md          # 商机、管道
    ├── product.md        # API 使用、功能
    └── marketing.md      # 营销活动、归因

用户问销售指标时，Agent 只读 sales.md。

# DOCX 处理
## 创建文档
用 docx-js 创建新文档。参见 [DOCX-JS.md](references/DOCX-JS.md)。

## 编辑文档
简单编辑直接修改 XML。
**修订模式**：参见 [REDLINING.md](references/REDLINING.md)
**OOXML 细节**：参见 [OOXML.md](references/OOXML.md)

：参考文件保持一层深度，不要嵌套太深。所有参考文件都应从 SKILL.md 直接链接。超过 100 行的参考文件，顶部加目录。

三、Skill 的结构组成

3.1 标准目录结构

每个 Skill 由一个必需的 SKILL.md 文件和可选的捆绑资源组成：

以 skill-name 为例，其目录结构大致如下：
├── SKILL.md # 必需：Skill 的入口和核心说明
│ ├── YAML Frontmatter # 必需：name + description
│ └── Markdown 正文 # 必需：使用指引
│
├── scripts/ # 可选：可执行代码（Python/Bash 等）
├── references/ # 可选：参考文档，按需加载
└── assets/ # 可选：输出用的资源文件

3.2 SKILL.md：Skill 的灵魂

SKILL.md 是 Skill 唯一必需的文件，分为两部分：

Frontmatter（YAML 元数据）

---
name: pdf-processor
description: 全面的 PDF 文档处理能力，支持文本提取、页面旋转、合并拆分、表单填充与水印添加。当需要处理 PDF 文件时使用，包括：(1) 提取 PDF 文本内容，(2) 旋转或调整页面方向，(3) 合并多个 PDF 或拆分 PDF，(4) 填写 PDF 表单，(5) 添加水印或页眉页脚。
---

• 同时说明「做什么」和「什么时候用」
  ——description 是 Skill 的主要触发机制

• 所有「何时使用」的信息都写在这里
  ——正文在触发后才加载，写在正文里没用

• 列举具体触发场景
  ——用 (1)(2)(3) 列出来，越具体越不容易误触发

• 覆盖所有使用方式
  ——用户可能用各种说法表达同一个需求，都要覆盖到

正文（Markdown 指令）

正文是 Agent 触发 Skill 后才会读取的内容，应该包含：

• 核心工作流程和步骤
• 关键判断点和决策逻辑
• 各资源文件的使用说明和加载时机
• 常见问题和注意事项
• 质量标准和验收要求

：始终使用祈使句/不定式（「做 X」「使用 Y」），不要用描述性语言（「这个 Skill 可以做 X」）。

3.3 三类捆绑资源

Scripts（脚本）

：

• 同样的代码被反复重写
• 需要确定性的、可重复的结果
• 操作复杂、容易出错

：scripts/rotate_pdf.py 用于 PDF 旋转任务

：token 效率高、结果确定、可以不读入上下文直接执行

：脚本可能仍需要 Agent 读取来做环境适配或修补

References（参考文档）

：

• Agent 工作时需要查阅的文档
• 详细的领域知识、规范、schema

：

• references/finance.md — 财务指标定义
• references/api_docs.md — API 接口文档
• references/policies.md — 公司政策

：

• 文件大（>10k 字）时，在 SKILL.md 中写明 grep 搜索模式
• 信息要么在 SKILL.md，要么在 references，不要重复
• SKILL.md 只保留核心流程指引，详细内容放 references

Assets（资产）

：

• 最终输出产物中需要用到的文件
• 模板、图片、字体、样板代码

：

• assets/logo.png — 品牌 Logo
• assets/slides-template.pptx — PPT 模板
• assets/frontend-boilerplate/ — 前端项目脚手架

：不加载到上下文，而是在输出中被使用/复制/修改

3.4 什么不该放进 Skill

Skill 应该只包含直接支撑其功能的必要文件。

创建这些多余文件：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

Skill 是给 AI Agent 用的，不是给人看的开源项目。额外的文档只会造成混乱和上下文浪费。

四、从问题到 Skill：创建方法

4.1 第一步：用具体例子理解需求

：你已经非常清楚 Skill 的使用模式。即使是改造现有 Skill，这一步也很有价值。

要创建一个有效的 Skill，必须先清楚地理解它会被如何使用——用具体的、真实的用户场景来定义。

1. 这个 Skill 要支持哪些功能？
2. 用户会怎么说？能举几个典型的用户提问例子吗？
3. 什么样的用户输入应该触发这个 Skill？
4. 期望的输出是什么样的？有格式或质量要求吗？

• ❌ 模糊理解：「用户要编辑图片」
• ✅ 具体理解：
  • 「把这张图里的红眼去掉」→ 触发图片修复功能
  • 「把这个 PDF 转成图片」→ 触发格式转换功能
  • 「帮我把这张图旋转 90 度」→ 触发旋转功能
  • 「给这张图加个水印」→ 触发水印功能

：不要一次问太多问题，先从最重要的开始，逐步深入。

4.2 第二步：规划可复用的内容

把具体例子转化为 Skill 内容，对每个例子做分析：

1. 如果从零开始执行这个任务，需要怎么做？
2. 反复执行这些工作流时，哪些脚本/参考/资产会有帮助？

用户需求	从零执行需要什么	可复用资源
帮我旋转这个 PDF	写 Python 代码用 PyPDF2 旋转页面	scripts/rotate_pdf.py
提取这个 PDF 的文字	写代码用 pdfplumber 提取	scripts/extract_text.py
合并这几个 PDF	写代码合并多个 PDF	scripts/merge_pdf.py

用户需求	从零执行需要什么	可复用资源
帮我做个待办应用	写 HTML/CSS/JS 脚手架 + 业务逻辑	assets/boilerplate/ 模板
做个数据看板	同样的脚手架 + 图表组件	assets/boilerplate/ 模板

用户需求	从零执行需要什么	可复用资源
今天有多少用户登录？	先查表结构，再写 SQL	references/schema.md
上月收入是多少？	先查财务表结构，再写 SQL	references/finance-schema.md

通过这个分析，你就能列出 Skill 需要包含的所有可复用资源：scripts、references、assets。

4.3 第三步：初始化 Skill 结构

用初始化脚本快速创建标准目录结构：

scripts/init_skill.py  --path 

脚本会自动创建：

• Skill 目录
• 带 frontmatter 和 TODO 占位符的 SKILL.md 模板
• scripts/、references/、assets/ 示例目录和文件

初始化后，根据需要自定义或删除生成的示例文件。

4.4 第四步：实现 Skill 内容

——先实现 scripts/references/assets 中的内容，再更新 SKILL.md。这样写文档时你已经清楚有哪些资源可用、怎么用。

实现脚本的注意事项

• 每个脚本都要

  实际运行测试
  ，确保没有 bug、输出符合预期
• 脚本很多时，至少测试代表性样本
• 不需要的示例文件和目录都删掉

写 SKILL.md 的注意事项

• 始终使用祈使句
• Frontmatter 的 description 要精心打磨
• 正文按工作流组织，不是按资源类型组织
• 明确告诉 Agent 什么时候读哪个 reference 文件
• 包含质量标准和验收要求

4.5 第五步：收尾和交付

开发完成后，确认以下事项：

1. ✅ 目录包含必需的 SKILL.md 文件
2. ✅ 所有需要的 scripts/、references/、assets/ 文件都在
3. ✅ 删除了占位文件、未使用的示例资源、缓存和临时输出
4. ✅ 运行了需要测试的脚本（或说明为什么没测）
5. ✅ 运行了验证脚本检查 frontmatter 和命名

：Skill 文件夹本身就是交付物。不要打包成 zip，也不要创建 .skill 文件。保持完整目录结构，这样可以直接作为文件夹加载。

五、确保 Skill 「好用」的设计技巧

5.1 触发准确率优化

触发不准是 Skill 最常见的问题。以下是优化 description 的几个技巧：

❌ description: 处理 PDF 文件
✅ description: PDF 文档处理，支持文本提取、页面旋转、合并拆分、表单填充、OCR 识别。
   当用户提到 PDF、pdf 文件、pdf 文档、扫描件转文字、pdf 转 word、合并 pdf、拆分 pdf 时使用。

❌ description: 文档处理
✅ description: 专业 PDF 文档处理（仅限 .pdf 格式）。
   不适用于 Word 文档、Excel 表格、PPT 演示文稿等其他格式。

❌ description: 图片相关的任务
✅ description: 图片编辑和处理，包括裁剪、缩放、旋转、格式转换、加水印、去背景、调整颜色、
   压缩优化。当用户要修改、处理、编辑、转换图片时使用。

5.2 执行质量保障

不要只说「生成一份报告」，要说「报告应包含 X/Y/Z 三个部分，每部分不少于 500 字，数据需标注来源」

• 好的输出长什么样，差的输出长什么样，对比展示
• 对容易出错的地方特别强调

• 列出 Agent 可能犯的错误
• 给出检测和纠正的方法

• 在工作流的关键节点加入检查点
• 告诉 Agent 完成后要做哪些验证

5.3 上下文效率优化

• 最常用的 20% 内容放 SKILL.md
• 偶尔用的放 references
• 几乎不用的放更深层的 reference 或干脆不放

• 结构化信息用表格，信息密度更高
• 决策逻辑用流程图式的判断树

可执行的内容用代码块，Agent 更容易识别和使用

六、常见陷阱与避坑指南

陷阱 1：把 Skill 写成了教程

：花大量篇幅解释概念、讲背景知识，Agent 根本不需要。

：直接给操作指令，假设 Agent 已经理解基础概念。需要背景知识的放 references，按需加载。

陷阱 2：description 太短或太泛

：description 只有一句话，导致触发不准。

：description 是 Skill 最重要的部分，值得花时间打磨。要包含功能描述 + 具体触发场景 + 边界说明。

陷阱 3：所有内容都塞在 SKILL.md

：SKILL.md 写了几千行，触发一次就占满大半上下文。

：遵循渐进式披露原则，按使用频率和场景拆分到 references。

陷阱 4：没有实际测试脚本

：脚本写了但没跑过，实际用的时候全是 bug。

：每个脚本都要实际运行测试，至少用一个真实用例验证。

陷阱 5：过度设计

：还没验证需求就做了一大堆功能，结果大部分用不上。

：先做最小可用版本，在真实使用中迭代。从最常见的 2-3 个用例开始。

七、总结：好 Skill 的设计清单

创建 Skill 前，用这份清单检查你的设计：

需求理解

• 有至少 3 个具体的用户使用场景
• 清楚用户会用什么说法触发这个 Skill
• 明确了 Skill 的边界（做什么、不做什么）

结构设计

• SKILL.md 控制在 500 行以内
• 详细内容拆分到了 references
• 重复代码封装成了 scripts
• 输出模板放在了 assets

内容质量

• description 写得具体、全面、边界清晰
• 正文用祈使句，直接给指令
• 有明确的质量标准和验收要求
• 包含了常见问题和注意事项

可交付性

• 所有脚本都经过实际运行测试
• 删除了所有占位文件和示例资源
• 目录结构清晰，命名规范
• 通过了基础验证检查

Skill 设计是一个持续迭代的过程。第一版不需要完美，先让它跑起来，在真实使用中发现问题、持续优化，才是打造高质量 Skill 的正确路径。