06 · 把重复的话写成文件
翔宇有一段时间每天都在跟 Claude Code 说同样的话：「用 pdfplumber 处理，先提取文本再处理表格，注意扫描件要走 OCR。」说了十几遍之后突
翔宇有一段时间每天都在跟 Claude Code 说同样的话：「用 pdfplumber 处理，先提取文本再处理表格，注意扫描件要走 OCR。」说了十几遍之后突然想——这些话能不能写下来，让它自己去读？顺着这个念头追下去，发现 Skills 的整个设计逻辑就藏在这个简单的想法里。——翔宇
要点速览
- 你将理解 Skills 的本质——把「你每次都要交代的话」写成一个文件，Claude 自己判断什么时候读
- 你将理解为什么 Skills 不需要写「PDF 是什么」这种 Claude 已经知道的事
- 你将理解渐进式加载的设计——为什么装一百个 Skill 也不会让 Claude 变慢
- 你将理解 Skills 和记忆（CLAUDE.md）的区别：一个是「遇到 X 怎么办」，一个是「我是谁」
1. 你反复说的那些话
从一个日常场景开始。
你用 Claude Code 处理 PDF，跟它说：「用 pdfplumber 打开，先提取文本，遇到表格特殊处理，扫描件走 OCR。」Claude 做得很好。
第二天又遇到 PDF。你又说了一遍。
第三天，又说了一遍。
到第五天，你开始烦了。
问题不是 Claude 不会做——第 1 篇讲过，Claude 住在你电脑上，你电脑上有 pdfplumber，它自然会用。问题是它不知道你想让它怎么用。
🎯 一句话理解 Claude 什么工具都会用，但它不知道你的工作流——先做什么、后做什么、遇到什么坑要绕。这些「怎么用」的指导方针，就是你每次都要重复的那些话。
那最直接的解法是什么？把这些话写下来。
2. 写成一个文件
把你反复说的那些话写进一个文件，叫 SKILL.md。内容大概长这样（不是代码，就是普通的文字）：
处理 PDF 时，用 pdfplumber 库。先提取文本内容，再处理表格。如果是扫描件（纯图片 PDF），走 OCR 流程。表格提取后转成 CSV 格式。注意：有些 PDF 的表格线是画上去的而不是真正的表格结构，需要特殊处理。
就这么简单。你把「每次都要说的话」写成了一份文档。
但光写下来不够——Claude 怎么知道什么时候该读这个文件？你不会希望每次都手动说「去读一下那个 PDF 的 Skill 文件」，那跟直接说指导方针有什么区别？
所以需要加一个东西：触发机制。
3. 加一个触发机制
SKILL.md 的文件开头有一段元数据（用三条横线包起来的部分），里面有两个关键字段：
name——这个 Skill 叫什么，比如「pdf-processor」。
description——这个 Skill 干什么、什么时候用。比如「从 PDF 提取文本和表格，填充表单，合并文档。当用户提到 PDF、表单或文档提取时使用」。
Claude 启动时会读所有 Skill 的 name 和 description。然后每次你给它一个任务，它拿你的请求和所有 Skill 的描述做匹配——就像搜索引擎匹配关键词一样。
你说「帮我处理这个 PDF」，Claude 扫一遍，发现 pdf-processor 的描述里有「PDF」「提取」「表单」——匹配度最高。于是它自动读取这个 Skill 的正文内容，就像你亲口说了那些话一样。
你什么都不用指定。
🧠 底层逻辑 这个自动触发机制的本质是信息匹配。description 就是 Skill 的「搜索关键词」——写得好，匹配精准；写得模糊（比如「帮助处理文件」），Claude 就分不清它和其他涉及文件的 Skill 有什么不同。所以 description 要具体，而且要包含触发术语。
这里有个容易忽略的细节：Claude 是自己判断用不用这个 Skill 的——你不需要告诉它「用 pdf-processor」。这和你可能用过的斜杠命令不同。斜杠命令是你输入 /format 它才执行，Skills 是 Claude 自己匹配自己触发。
什么时候你会更倾向于手动指定？当你的请求比较模糊，或者你装了很多 Skill 可能导致 Claude 选错的时候。这时候你可以在请求里直接说「用 pdf-processor 来处理」——但大多数时候不需要。
4. 加入参数化
现在你有了一个会自动触发的指导方针文件。但一个 Skill 能做的事不止这些。
SKILL.md 的元数据部分还可以设置两个可选字段：
allowed-tools——限制 Claude 在执行这个 Skill 时能用哪些工具。比如一个纯分析的 Skill，你可以限制成 Read, Grep, Glob——Claude 能看文件但不能改。这就像给助手一个「只读权限的门禁卡」。
model——指定用哪个模型。有些 Skill 需要深度推理用 Opus，有些简单任务用 Haiku 就够了，更快更便宜。
💬 通俗讲 想象你招了一个助手，给他一本操作手册。手册里不光写了「怎么做」，还写了「你能动什么、不能动什么」（工具权限）和「这件事该用什么级别的专注度」（模型选择）。一本手册 = 做事方法 + 权限范围 + 专注度。
这些配置看起来像「代码逻辑」，但本质上它们还是在修改 Claude 的工作环境——告诉系统「当这个 Skill 激活时，限制工具集为 XYZ」。没有执行任何程序，只是改变了 Claude 接下来工作的参数。
5. 完整的 Skills 体系
到这里，一个完整的 Skill 就搭好了。回头看一下我们是怎么一步步搭起来的：
你反复说同样的话 → 把话写成文件 → 加触发机制让 Claude 自己判断什么时候读 → 加参数控制权限和模型
这就是 Skills 的全部。
但当你开始装很多 Skill 时（十几个、几十个），一个新问题出现了：这些 Skill 的内容会不会把 Claude 的上下文窗口塞满？
回到第 2 篇的概念——上下文窗口是一张桌子。如果你有一百个 Skill，每个正文一千行，全部加载就是十万行。桌子上连放你实际工作资料的空间都没了。
这就引出了一个很漂亮的设计。
6. 渐进式加载——装得多用得少
Claude Code 用了一个三级加载策略来解决这个问题。
第一级：元数据常驻。 每个 Skill 的 name 和 description（几十个词）在启动时就加载到上下文里。一百个 Skill 的元数据加起来也就几千个 token——几乎不占空间。这是 Claude 用来做匹配的「索引目录」。
第二级：正文按需加载。 SKILL.md 的正文只在被触发时才读进上下文。你一天可能只触发三四个 Skill，另外九十六个的正文根本不进桌子。
第三级：支持文件按需加载。 SKILL.md 旁边可以有 references/、scripts/ 等目录。这些文件只在 Claude 执行过程中判断「需要参考」时才去读。
🎨 打个比方 你是一个办案的侦探，手头有一百个案件的卷宗。你不会把一百个卷宗全打开铺在桌上——桌子上连放杯咖啡的地方都没有。你只需要一个案件清单（元数据），当前查的那个案打开卷宗（正文），需要看法医报告时再从柜子里拿（支持文件）。
想一想：如果没有渐进式加载会怎样？你装的 Skill 越多，Claude 反而越慢、越贵、质量越差——因为上下文被大量无关内容塞满，每条信息分到的注意力越少（第 5 篇讲过这个原理）。渐进式加载让「装很多 Skill」变成零成本的事——只要不触发，它们不占任何空间。
7. 一个常见的写作错误
聊到这里，有一个写 SKILL.md 时常见的错误值得说。
很多人会在 Skill 里写大量背景知识——「PDF 是什么」「pdfplumber 是一个 Python 库，由 Jeremy Singer-Vine 开发……」
这些信息 Claude 已经知道了。
Skills 的设计前提是：Claude 是一个非常聪明的助手，只是不知道你的具体工作流程。 你需要告诉它的是「我们这个项目处理 PDF 时用 pdfplumber 而不是 PyMuPDF」「表单填充先分析字段再验证再填写」——这些它不知道的东西。不是 PDF 的维基百科词条。
官方建议 SKILL.md 正文控制在 500 行以内。这不是随便定的数字——正文太长，加载时占过多上下文空间，Claude 的注意力也被稀释。如果你的 Skill 确实需要大量参考信息（详细的 API 文档、数据库表结构），把它们放在 references/ 目录里，正文只放指向这些文件的链接。Claude 需要时自己去读，不需要时不占空间。这就是渐进式加载的实际应用。
8. 内置的 Skills
Claude Code 自带几个开箱即用的 Skills，以斜杠命令的形式存在。
/batch——批量处理文件。对多个文件做相同操作。
/loop——循环执行。适合「跑测试 → 修 Bug → 再跑测试」直到全部通过的场景。
/simplify——简化代码。让 Claude 审视一段代码，找出可以简化的地方。
/debug——调试模式。更系统地分析报错和 Bug。
/claude-api——查询 Claude API 文档。
这些内置 Skills 和自定义 Skills 的区别：内置的用斜杠命令触发（你输入才执行），自定义的是 Claude 自动匹配触发。底层机制一样——都是往上下文里注入一段指导方针。
9. 存放位置和作用范围
Skills 放在哪里，决定了谁能用它。
个人 Skills——放在 ~/.claude/skills/ 下。你在任何项目里启动 Claude Code 都能用。适合存你的个人工作流——你喜欢的代码审查流程、你常用的文档格式。
项目 Skills——放在项目根目录的 .claude/skills/ 下。只在这个项目里生效。好处是可以通过 git 共享给团队——队友拉代码后自动获得这些 Skills。适合项目特有的规范——「这个项目的 API 响应格式」「这个项目的数据库迁移流程」。
这个分层和第 3 篇讲的记忆系统逻辑一样：个人偏好放用户级，项目规范放项目级。
10. Skills 和 CLAUDE.md 的区别
Skills 和记忆（CLAUDE.md）都是「写给 Claude 看的文字」。它们解决的是同一个问题还是不同的问题？
不同的问题。
🔑 关键点 记忆（CLAUDE.md）回答的是「我是谁」——项目用什么技术栈、你的代码风格偏好、构建命令是什么。Skills 回答的是「遇到特定任务怎么做」——处理 PDF 的流程、代码审查的清单、commit message 的格式。记忆是身份，Skills 是方法论。
CLAUDE.md 在每次对话开始时就加载。Skills 只在匹配到相关任务时才加载。CLAUDE.md 描述的是持久的偏好和规则，Skills 描述的是针对特定任务的工作流程。
11. 串起来：概念网络中的位置
现在我们有了六个概念。
位置（第 1 篇）→ AI 住在你电脑上，能用你的工具。 上下文（第 2 篇）→ 它通过一张有限的桌子看你的代码。 记忆（第 3 篇）→ CLAUDE.md 和 Auto Memory 让它不用每次从零开始。 对话（第 4 篇）→ 你怎么设计信息包决定了输出质量。 思考（第 5 篇）→ effort 控制它处理信息的深度。 技能（本篇）→ 把「你每次都要说的话」打包成可复用的文件，Claude 自己判断什么时候读。
从搭建过程回看整个设计：重复的指导方针 → 写成文件 → 自动触发 → 参数控制 → 渐进式加载。每一步都是在解决前一步带来的新问题。这就是 Skills 的设计逻辑。
12. 自检问题
这篇从零搭建了一个概念：Skills 是把你反复说的指导方针打包成文件，由 Claude 自动匹配触发。
费曼检验时间：
- 有人说「Skills 就像浏览器插件，安装了就有新功能」。你能解释这个类比为什么不准确吗？Claude 本来就会处理 PDF，那 PDF Skill 给了它什么？
- description 字段为什么是 Skills 设计中最关键的部分？如果你写了一个 description 叫「帮助处理文件」，会出什么问题？
- 渐进式加载为什么重要？如果没有这个机制——所有 Skills 的全部内容在启动时全量加载——会出什么具体问题？
- 你的朋友问：「CLAUDE.md 和 Skills 有什么区别？都是写给 AI 看的文字啊。」你怎么解释？