Skill 学习指南：给 AI Agent 装一本“专项操作手册“

Skill 是扩展 AI Agent 能力的模块化知识包。这篇文章从目录结构、SKILL.md 规范、三级加载机制到完整实战案例，帮你从零理解并写出第一个可用的 Skill。

一、什么是 Skill：与 Prompt、MCP 的边界

写 prompt 时你大概率遇到过这种场景：System Prompt 写了几百行规范，当前对话里 AI 执行得很好，换个会话一切归零。问题出在 prompt 的定位------它是一次性指令，无法固化为跨会话复用的能力。

Skill 解决的是这个问题。它的本质是一个可复用的能力模块：

ini 复制代码

Skill = 专业知识 + 操作流程 + 工具调用

三个概念的边界可以这样划分：

维度	System Prompt	MCP	Skill
本质	一次性角色设定	工具/能力扩展协议	可复用行为约束
解决什么问题	临时调整 AI 风格	AI 连不到外部系统	AI 不按规范工作
需要写代码	否	是（Server/Client）	非必须，纯 Markdown 即可
持久性	仅当前对话	持久（服务常驻）	持久（文件存储）
面向人群	所有人	开发者	所有人

三者不是替代关系，而是互补关系。一个常见误解是「Skill 会取代 MCP」------实际恰好相反：MCP 是水管，Skill 是工人。拿红狐 hub 上的「多平台违禁词检测」Skill 举例，检测脚本需要调用红狐的数据接口（redfox.hk）拿最新词库，这个连接通过 API 通道完成；而「什么词算高风险、检测完怎么给替换建议、报告用什么格式输出」这些判断标准，来自 Skill 的 references 文档。流程是 Skill 给的，数据通道是 API 给的，各司其职。

二、标准目录结构

一个 Skill 在磁盘上就是一个目录，只有 SKILL.md 是必需的：

objectivec 复制代码

skill-name/
├── SKILL.md          ← 必须有，核心文件
└── （可选资源）
├── scripts/          ← 可执行脚本（Python/Bash 等）
├── references/       ← 参考文档（按需加载）
└── assets/           ← 静态资源（模板、图片、字体等）

三、SKILL.md 规范：YAML Front Matter + 五要素

SKILL.md 使用 YAML Front Matter + Markdown 正文的格式。name 是技能唯一标识符，description 描述触发场景------AI 据此判断何时使用：

markdown 复制代码

---
name: skill-unique-name      # 技能的唯一标识符
description: |               # 触发场景描述（AI 据此判断何时使用）
Use when doing X.
Use BEFORE doing Y.
这个 Skill 做什么，什么时候触发它。
---

# 技能正文（Markdown）  # 给 AI 的操作指南

## 核心原则
- 原则一
- 原则二

## 执行流程
1. 第一步
2. 第二步
3. 第三步

## 禁止行为
- 禁止做 A
- 禁止跳过 B

正文通常包含五个要素：

Metadata（元数据）：name + description
Context（适用上下文）：适用场景和前提条件
Process（执行流程）：步骤化工作流，可包含 checklist
Constraints（约束规则）：禁止行为、必须遵守的原则
Output Format（输出规范）：结果应如何呈现

四、三级加载机制：上下文成本控制的关键

Skill 采用"按需加载"设计，避免浪费上下文窗口：

级别	内容	何时加载	大小
第一级	name + description	始终在上下文中	~100 词
第二级	SKILL.md 正文	Skill 被触发后	< 5000 词
第三级	scripts/ references/ assets/	AI 判断需要时	无限制

实际效果：AI 随时知道有哪些 Skill，但只有真正需要时才"打开"它。这意味着可以安装大量技能而不撑爆上下文。

五、三类可选资源详解

scripts/：确定性脚本

把反复编写的代码固化成可直接执行的脚本，执行时不需要读入上下文，节省 token：

bash 复制代码

scripts/rotate_pdf.py      # 旋转 PDF
scripts/decrypt_ncm.py     # 解密音频
scripts/parse_log.py       # 分析日志

references/：参考文档

存储 AI 需要参考但不必一直占用上下文的知识（数据库表结构、API 文档、公司政策）。设计原则：按领域拆分------用户问销售数据时只加载 sales.md，不加载 finance.md。

assets/：静态资源

输出中会用到的模板和文件：前端模板、PPT 模板、品牌 Logo、checklist 模板。

在 SKILL.md 中引用资源的方式：

markdown 复制代码

---
name: code-review
description: Use when reviewing code changes before merging.
---

## 参考规范
请在审查前阅读 reference/style-guide.md 中的编码规范。

## 执行流程
1. 运行 scripts/validate.sh 做静态检查
2. 按照 assets/checklist.md 逐项审查
3. 使用 assets/templates/report.md 格式输出结果

六、创建 Skill 的六步流程

第 1 步：明确使用场景。 用户会说什么话触发？期望完成什么任务？典型输入/输出是什么？

第 2 步：规划可复用资源。 对每个用例问："完成这个任务，每次都需要重写什么代码/重查什么文档？"整理成 scripts/、references/、assets/ 的规划清单。

第 3 步：初始化。 用脚手架脚本生成标准目录结构和 SKILL.md 模板：

bash 复制代码

python scripts/init_skill.py <skill-name> --path <输出目录>

第 4 步：编写内容。 description 要清晰全面；正文控制在 500 行以内，细节放 references/；用祈使句/动词开头（"运行脚本...""读取文件..."）；脚本写完必须实际运行测试；参考文档超过 100 行要加目录。

第 5 步：打包发布。 打包前自动校验 YAML frontmatter 格式、必填字段完整性、目录结构规范，通过后生成 .skill 文件（本质是 zip 包）：

bash 复制代码

python scripts/package_skill.py <skill目录路径>

第 6 步：迭代优化。 在真实任务中使用，观察 AI 表现，持续改进。

七、三条核心设计原则

原则 1：精简优先。 上下文窗口是公共资源。每加一段文字都问自己："这是 AI 不知道的信息吗？删掉会有什么后果？"不要写"在开始之前，你需要理解这个任务的重要性..."，直接给操作步骤。

原则 2：自由度要匹配任务。

任务特性	自由度	写法
步骤固定、易出错	低	具体脚本 + 严格参数
有首选方案、允许变化	中	伪代码 + 可配置参数
多种方案均可、依赖上下文	高	文字指导 + 启发式原则

原则 3：渐进式披露。 SKILL.md 只放核心工作流，细节通过引用指向 references/ 文件，所有引用保持一层深度。

八、常见误区

误区	正确做法
在 SKILL.md 正文写"何时使用"	应写在 description 字段（正文触发后才加载）
创建 README.md、CHANGELOG.md	只保留任务必需的文件
把所有细节塞进 SKILL.md	细节放 references/，SKILL.md 只放核心流程
跳过脚本测试	脚本必须实际运行验证
深层嵌套引用	所有 references 文件从 SKILL.md 一层引用

九、实战：拆一个真实在用的 Skill

先看一个最小案例 pdf-rotator，把结构跑通：

markdown 复制代码

pdf-rotator/
├── SKILL.md
└── scripts/
    └── rotate_pdf.py

markdown 复制代码

---
name: pdf-rotator
description: |
旋转 PDF 文件中的页面。当用户需要旋转 PDF 页面、
修正扫描件方向时使用。触发词：旋转 PDF、PDF 页面方向
---

# PDF 旋转工具

## 使用方法

运行 `scripts/rotate_pdf.py`：

```bash
python scripts/rotate_pdf.py --input input.pdf --output out.pdf --angle 90

参数说明：

--angle：旋转角度，可选 90、180、270
--pages：指定页码（如 1,3,5），不填则旋转所有页

yaml 复制代码

再来看一个工程场景更复杂的例子：TDD 技能。它的 SKILL.md 强制"红-绿-重构"循环，并明确禁止行为：

```markdown
---
name: test-driven-development
description: |
Use this skill when the user asks to implement any feature, function, or module.
Enforces Test-Driven Development (TDD) workflow: write tests FIRST, then implementation.
---

## 核心原则

**红-绿-重构（Red-Green-Refactor）循环：**

1. **红（Red）**：先写一个失败的测试
2. **绿（Green）**：写最少的代码让测试通过
3. **重构（Refactor）**：优化代码，保持测试通过

## 禁止行为

- ❌ 禁止先写实现代码再补测试
- ❌ 禁止跳过测试直接给实现
- ❌ 禁止在同一个回复中同时给出测试和实现（除非用户明确要求）
- ❌ 禁止写没有断言的测试

这类技能的价值在于：问题往往不是"AI 不懂"而是"AI 不按规范做"。Skill 把规范变成可执行的结构化约束，AI 被强制按流程工作。

案例拆解：visual-ops-writer 的三层结构

再来拆一个生产环境真实在用的（visual-ops-writer，图文运营创作 Skill）。它的目录结构完整对应 Skill 的三层设计：

bash 复制代码

visual-ops-writer/
├── SKILL.md                  # 入口：告诉 AI 这是什么、怎么用（任务定义层）
├── references/               # 参考手册：AI 干活时查阅的知识（领域知识层）
│   ├── core_workflow.md      # 核心执行流程（四模式分支）
│   ├── writing-framework.md  # 写作框架（8 条铁律 + 9 步结构）
│   └── quality-check-guide.md # 质检与 SEO 规范
├── scripts/                  # 执行层：真正干活的代码（执行能力层）
│   ├── validate_article.py   # 质量检查脚本
│   ├── check_prohibited_words.py # 违禁词三级检测
│   └── generate_image.py     # 配图生成
└── assets/                   # 模板和素材

三层各解决一个问题：

SKILL.md 是"任务定义"：YAML 头里的 name、description、触发词让 AI 判断"什么时候该激活这个技能"，解决"AI 知不知道有这个能力"
references/ 是"领域知识"：如"每段不超过 5 行""禁用行业黑话"这些判断标准放在文档里按需查阅，解决"AI 知不知道做这件事的标准"
scripts/ 是"执行能力"：质检、违禁词检测、生图都是 Python 脚本在跑，AI 负责调度并读取 JSON 报告，解决"AI 能不能真正动手干活"

一句话概括这套机制："任务定义 + 领域知识 + 执行脚本"的结构化能力包。

案例拆解：微博评论分析的数据管道

最后看一个数据管道型的 Skill------红狐 hub 上的「微博评论分析」。它的工作一句话讲完：丢一条微博链接进去，把这条博文下的评论拉出来------谁评论的、说了什么、被赞多少次、什么时候发的，点评论人昵称还能直接跳进 TA 的微博主页。

它之所以能干这件事，是因为背后接了红狐的数据服务：每次查询实时拉取平台刚更新的数据，不用旧缓存糊弄你。累计 1 万多次调用，每一次靠的都是管道，不是措辞。这正对应判断 Skill 成色的标准------把 Skill 里的 prompt 删掉，剩下的东西还能不能干活。能，它是工具；不能，它就是一份写得比较讲究的 prompt。

十、生态：skill-creator、Superpowers 与技能市场

skill-creator 是 Anthropic 官方的"母技能"（Meta-Skill）------一个用来创建技能的技能。用自然语言描述需求，它会先确认细节，再自动设计结构并生成完整的 SKILL.md：

bash 复制代码

直接告诉 ClaudeCode：
1、"帮我写一个 XXX 的 Skill"
2、"创建一个用于 YYY 流程的技能文件"
3、或者直接输入 /skill-creator

Superpowers 是开源技能系统，更像"给 AI 的软件工程培训包"：14 个核心技能（brainstorming、writing-plans、TDD、systematic-debugging、requesting-code-review、verification-before-completion 等）串联成完整开发工作流。安装方式：

bash 复制代码

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

技能市场：skills.sh 是社区精选集（按领域分类、有评分和使用量统计、一键安装）；Anthropic 官方仓库（github.com/anthropics/skills）提供最权威的格式规范和最佳实践。面向中文内容运营场景，红狐 hub（redfox.hk/skills）是另一个值得逛的市场------上百个现成的数据与运营类 Skill（内容创作、数据分析、平台运营三大类），装上就能用，且背后普遍有真实数据通道。

十一、小结

Skill 的本质：抽象（从具体任务提炼通用模式）→ 封装（知识流程化、结构化）→ 复用（一次构建，持续使用）。

动手路径很直接：挑一个你每天都在做、却每次都要重新交代 AI 的任务，写成 SKILL.md，跑起来，迭代它。当你把个人工作方法论固化为 Skill 文件时，AI 就从"听话的工具"变成了"有专业素养的协作者"。

参考资料

Anthropic 官方技能仓库：github.com/anthropics/...
skills.sh 社区技能市场：skills.sh/
Superpowers 项目：github.com/obra/superp...

红狐 hub 相关页面（功能与调用数据均取自各 Skill 页面公开信息）：

Skills 广场：redfox.hk/skills?sour...
「微博评论分析」：redfox.hk/skills/no/h...
「多平台违禁词检测」：redfox.hk/skills/no/w...