夜雨聆风
为什么你的 AI 助手总是不"懂你"？
你有没有遇到过这种情况——
明明花了大半天写了一份详细的"AI使用指南"，告诉它要用什么语气、要做哪些步骤、要避开哪些坑。结果用的时候，AI要么漏掉关键步骤，要么一顿输出全是废话。
问题出在哪？大概率是你把"工作手册"和"全局规则"混在一起写了。今天要聊的 Claude Skills，正是解决这个问题的思路——它是一套让 AI 真正"学会"某个技能的方法论。
一、Claude Skills 到底是什么？
先说个真实的场景。你是一个科技博主，每天要写好几篇公众号文章，每篇都要经历：选题→查资料→列大纲→写正文→配图→排版→上传到公众号后台。
传统做法是给 AI 一个超长的 prompt，告诉它："你是一个科技博主，写文章要用什么风格……"写得越多，上下文越长，AI 的注意力越分散，最后输出的内容往往走样。
Claude Skills 提供了另一种思路。它本质上是一套目录约定，约定了一个文件夹结构：
wechat-article-writer/ ← Skill 根目录├── SKILL.md ← 核心文件，定义这个 Skill 怎么用├── scripts/ ← 辅助脚本（如自动排版脚本）├── assets/ ← 素材资源├── references/ ← 参考文档（如写作风格指南）└── outputs/ ← 输出文件
当你对 AI 说"帮我写一篇公众号文章"的时候，AI 才会去读 SKILL.md；平时它就静静地躺在那里，不占任何上下文。
这个设计哲学很反直觉：不是塞得越多越好，而是需要的时候才出现。
二、SKILL.md 的三层加载机制
Anthropic 在 Skills 文档里提到了一个核心概念：Progressive Disclosure（渐进式披露）。这个概念在 UI 设计里早就有了——就像软件的设置页面，常用选项放最顶层，高级选项藏在二级菜单里。SKILL.md 用的也是这个思路，分成三层：
SKILL.md 三层加载机制：frontmatter 始终扫描 → SKILL.md 正文触发加载 → 外部资源按需引用
第一层：frontmatter（始终扫描）
SKILL.md 文件开头有一段 YAML 格式的配置，叫 frontmatter，里面只有两个字段：name 和 description。Claude 每次启动时都会扫描一次。
---name: wechat-article-writerdescription: 当用户需要写公众号文章、技术博客，或说"帮我写一篇""/write"时使用---
第二层：SKILL.md 正文（触发后加载）
当用户的请求匹配上 description 描述的场景，Claude 才会把整个正文读进上下文。这一层定义的是这个 Skill 的具体工作流程。
第三层：外部资源（按需引用）
如果 SKILL.md 正文中明确写了"请去读 references/style-guide.md"，Claude 才会去读那部分内容。三层按需加载，不多余占用 token。
三层加载顺序：frontmatter（始终扫描）→ SKILL.md 正文（触发加载）→ 外部资源（按需引用）这个设计解决了一个核心问题：几千行的 SKILL.md 为什么是灾难？因为每次触发都要全部加载进上下文。哪怕你只是想让它帮你检查标题格式，它也得先把整个工作流读完，token 消耗暴涨，模型抓不到重点。
正确的做法是拆分。比如数据分析本来可以写成一个 mega-SKILL.md（数据清洗+可视化+异常检测混在一起），拆成三个独立 Skill 更好：data-cleaning、data-visualization、anomaly-detection，每个只写自己这一块，最多三五百行。模型不需要的时候，这三个文件夹就静静地躺着，一个字符都不进上下文。
你写得越精炼、拆得越干净，模型每次触发时的注意力越集中，输出质量反而越高。
三、SKILL.md vs 系统 prompt vs MCP：三个边界
用一个类比来解释。如果把 Claude 想象成一个新入职的员工，这三个东西分别对应他工作中的三类信息：
系统 prompt = 性格价值观 | SKILL.md = 工作手册 | MCP = 外部工具接口
三个东西互相不可替代
- 系统 prompt
决定模型的"性格基线"——说话方式、价值取向、是不是用 markdown。这部分无论用户问什么都生效 - SKILL.md
决定模型在某个具体任务里的工作方式。如果用户根本不需要这个任务，把内容塞进系统 prompt 就是浪费 token - MCP
决定模型能够到什么外部资源。你可以在 prompt 里让模型"假装"在调用数据库，但 MCP 给的是真能力
判断顺序：新需求该往哪儿落？
① 先问"需要新能力吗" 如果模型自己干不了（要访问公司内部系统、要调用某个 SaaS 工具、要操作真实文件），那就是 MCP 的活。
② 再问"需要新流程吗" 如果不需要新能力，只是需要换一种做事方式（写公众号文章、做合同审查、生成测试用例），那是 SKILL.md 的活。
③ 最后问"这是全局基调吗" 只有"无论用户问什么都要保持的设定"，才进系统 prompt。比如团队约定不用 emoji、所有代码必须有类型注解。
三步问完，新需求该往哪儿落，就清楚了。
四、description 字段：触发开关，不是说明文档
这是最容易踩坑的地方。很多人的 description 写成这样：
# 错误示范name: data-analysisdescription: 用于数据分析的 skill# 还是错误示范name: report-writerdescription: 写报告
这种 description 写完，等于这个 Skill 装了等于没装。模型根本不知道什么时候该触发它。
要理解这件事，得先理解模型是怎么"看到"你的 Skill 的。在每一次对话开始时，Claude 会扫描所有可用 Skill 的 frontmatter（只有 name 和 description 这两个字段会进上下文，正文不会）。当用户发来请求，模型做的事和搜索引擎匹配关键词非常像——它会判断用户的请求跟哪个 Skill 的 description 在语义上最接近，然后决定要不要把对应的 SKILL.md 正文加载进来。
也就是说，description 不是给人看的说明，是给模型看的检索词典。
正确的 description 必须满足三个要求
- 第一，包含明确的触发场景
——不是"用于 XX"，而是"当用户想要 XX 时使用" ❌ 不要写： 用于数据分析✅ 要写：当用户提供 CSV/Excel 数据并要求分析、可视化、检测异常时使用 - 第二，包含用户最可能说出的关键词
——用户会用什么词来描述这个需求？把这些词都铺在 description 里。比如"公众号文章""技术博客""生成文章""/write"这些词，因为这是用户实际会说的话 - 第三，保持 1-2 句话
——太短，关键词不够，触发不到；太长，反而冲淡信号，模型抓不到重点。Anthropic 官方的 docx、xlsx、pdf 这些 Skill 的 description 都很短小，但每一个词都是关键词。
五、一个判断标准
一个写得好的 SKILL.md，光看 frontmatter 就能判断。description 写得像一句话需求描述、能让你立刻判断"什么场景用什么不用"的，是写得好的。描述写得像"用于 XX 处理"这种功能性短语的，基本上是写得差的——这种 Skill 装上去模型也很难触发，触发了正文如果还是 几千行，那就是双重灾难。
AI 注意力管理：不是塞得越多越好，而是需要的时候才出现
Claude Skills 不是 prompt 的复制粘贴，也不是文档目录的搬运。它是一套用 Progressive Disclosure 思想来管理模型注意力的机制。理解了这一点，你写出来的 Skill 才不会像一份冗长的员工手册，而是像一个真正能被随时翻出来用的工具。
下次给 AI 写"使用指南"之前，先想一个问题：
这份信息，是任何时候都要用的全局设定，还是只有特定场景才需要的工作流程？想清楚了，你就知道该往哪儿写了。
扩展阅读：
一文搞懂 AI Skills 技术原理：模块化架构是怎么让大模型"长出"技能包的
