你有没有想过，为什么有些 AI 助手能精准地帮你处理特定任务——按你公司的规范写代码、用你习惯的格式整理文档、调用你常用的工具？秘密就在于 Skill（技能）。这篇文章带你从零理解并写出自己的第一个 Skill。

什么是 Skill？

Skill 是一个模块化、自包含的能力包，用来扩展 AI 助手的能力。简单说，它给 AI 补充了三样东西：

  • 专业工作流：某个领域的多步骤操作流程
  • 工具集成：如何处理特定文件格式或调用特定 API
  • 领域知识：公司专属规范、数据结构、业务逻辑

打个比方：通用 AI 就像一个聪明但刚入职的新人，而 Skill 就是你交给他的岗位手册——看完他就知道”在你这儿，事情该怎么做”。

一个 Skill 长什么样？

Skill 的本质是一个文件夹，核心是一个 SKILL.md 文件：

skill-name/
├── SKILL.md          （必需）
│   ├── YAML 头部信息（name + description）
│   └── Markdown 正文（具体指令）
└── 可选资源
    ├── scripts/      可执行脚本
    ├── references/   参考文档
    └── assets/       输出用的素材文件

最小的 Skill 只需要一个 SKILL.md，其他都是可选的。

SKILL.md 的基本结构

一个 SKILL.md 由两部分组成：YAML 头部 + Markdown 正文。

---
name: pdf-processor
description: 处理 PDF 文件的技能，包括提取文本、合并、拆分、填写表单。当用户需要读取、编辑或转换 PDF 时使用。
---

# PDF 处理技能

## 何时使用
当用户需要对 PDF 做以下操作时：
- 提取文本或表格
- 合并/拆分 PDF
- 填写 PDF 表单

## 操作步骤
1. 先确认 PDF 文件路径
2. 根据需求选择对应工具
3. ...

头部两个字段最关键

字段作用写法要点
name技能名称全小写，用连字符分隔，如 pdf-processor
description技能描述决定 AI 何时触发这个技能，必须写清”做什么 + 什么时候用”

description 是重中之重。AI 就是靠它来判断”当前任务要不要用这个技能”。写得含糊，技能就不会被触发。

  • ❌ 差：”一个处理文件的工具”
  • ✅ 好：”处理 PDF 文件，包括提取文本、合并、拆分、填表。当用户需要读取、编辑或转换 PDF 时使用。”

核心设计原则

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

上下文窗口是公共资源。 只补充 AI 不知道的内容，不要把它已经会的东西再写一遍。

AI 已经知道通用编程、常见格式、基础常识——这些不用写。你要写的是它不知道的：你的业务规则、你的文件命名规范、你踩过的坑。

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

这是 Skill 设计最精妙的地方。信息分三层加载，用多少读多少：

第 1 层：name + description  → 始终在上下文里（占用极小）
第 2 层：SKILL.md 正文       → 技能被触发时才加载
第 3 层：references/ 等资源   → 真正需要时才读取

好处：平时几乎不占用上下文，只有真正用到时才展开细节。这样你可以写很详细的技能，而不用担心拖慢 AI。

实践建议：SKILL.md 正文保持精简（几百行以内），把大段的参考资料、示例、schema 放到 references/ 目录，正文里用一句话指引”需要时去读 references/xxx.md”。

手把手：写你的第一个 Skill

假设你要做一个”周报生成”技能，规范团队周报格式。

第 1 步：想清楚具体场景

先用具体例子问自己：

  • 用户会怎么触发它？（”帮我写周报”、”整理本周工作”）
  • 输入是什么？（零散的工作记录）
  • 输出是什么？（固定格式的周报）

第 2 步：创建文件夹和 SKILL.md

mkdir weekly-report
cd weekly-report

创建 SKILL.md：

---
name: weekly-report
description: 按团队规范生成周报。当用户要求写周报、总结本周工作、生成工作汇报时使用。
---

# 周报生成技能

## 周报格式规范
1. 标题：【周报】姓名 + 日期范围
2. 分三块：本周完成、下周计划、风险与阻塞
3. 每条用动词开头，量化结果（如"完成登录模块，覆盖率 85%"）

## 生成步骤
1. 收集用户提供的零散工作记录
2. 按三块归类
3. 每条改写为"动词 + 结果"格式
4. 套用标题模板输出

## 注意事项
- 空的模块写"无"，不要留空
- 风险项要给出应对建议

第 3 步：放置到正确位置

Skill 分两级存放：

级别存放位置适用范围
用户级~/.workbuddy/skills/你个人所有项目通用
项目级{项目}/.workbuddy/skills/团队共享，跟项目走

周报这种个人习惯，放用户级；如果是团队规范，放项目级让大家共用。

第 4 步：测试与迭代

写完不是结束。真实用几次，看看：

  • 触发准不准？（description 要不要调）
  • 输出合不合预期？（正文指令要不要补）

Skill 是迭代出来的，不是一次写完的。

进阶：三个可选资源目录

当技能复杂时，用这三个目录组织资源：

scripts/ — 可执行脚本

放置技能要用到的代码。比如一个数据清洗脚本，AI 可以直接调用而不用每次重写。

references/ — 参考文档

放大段的背景知识、API 文档、数据结构说明。正文里只需一句话引导：

详细的 API 字段说明见 references/api-schema.md

AI 需要时才去读，平时不占上下文。

assets/ — 输出素材

放置生成结果时要用到的模板文件、图片、样式表等。比如生成 PPT 用的模板、生成网页用的 CSS。

常见误区

误区正确做法
description 写得太笼统明确写”做什么 + 何时用”
把 AI 已会的常识写进去只写它不知道的专属知识
所有内容堆在 SKILL.md大段资料拆到 references/
写完不测试真实使用中反复迭代
一个技能塞太多功能一个技能聚焦一件事

写在最后

Skill 的本质，是把你脑子里的”隐性经验”变成 AI 能读懂的”显性指令”。

  • 你越懂某个领域，越知道 AI 会在哪里出错——那些地方就是你该写进 Skill 的
  • 好的 Skill 不是越长越好，而是恰好补齐 AI 缺的那部分
  • 从一个小而具体的场景开始，写完就用，用完就改

当你为常做的任务都配好 Skill，AI 就从”通用助手”变成了”懂你的专属助手”。这才是 AI 真正提效的地方。

核心要点回顾：

  • Skill = 一个含 SKILL.md 的文件夹
  • description 决定技能何时被触发，务必写清晰
  • 遵循”简洁”和”渐进式披露”两大原则
  • 复杂内容拆到 scripts / references / assets
  • 写完必须真实测试、持续迭代

适合人群：想让 AI 更懂自己工作场景的开发者、内容创作者、效率工具爱好者

动手建议：挑一个你每周都要重复做的任务，今晚就写个 Skill 试试