Claude 的 Skill 不是一个勾选框。它是一个文件夹，里面有一份 SKILL.md：开头一小段 YAML（一个 name、一个 description），下面是一段 markdown 指令，外加可选的脚本和参考文件。Skills 在 2025 年 10 月上线，如今已是给 Claude 加一项可复用能力的标准做法，claude.ai、Claude Code、Claude API 三个面都通用。一件没人一上来就告诉你的事：一个 Skill 会不会触发，几乎全看一个字段——description——因为它是 Claude 每次回复前唯一会读的部分。
这篇把”你发一句话”到”Skill 真正跑起来”中间发生的事拆开讲，点名那些真会坑到你的硬限制，并给出最常见故障（Skill 从来不触发）的修法。
一句话总结
- Claude 启动时只把每个已装 Skill 的
name+description预载进系统提示——每个 Skill 大约 100 token——只有匹配上之后才去读SKILL.md的其余部分。这就是 Anthropic 说的”渐进式披露”（progressive disclosure）。 description就是触发器。硬限制（截至 2026 年 6 月）：name最多 64 个字符（小写字母、数字、连字符，不能含 “anthropic”/“claude”）；description最多 1024 个字符，要用第三人称写。- 一个 Skill 从来不触发，90% 是描述的问题。先改描述，再去碰 instructions。
SKILL.md正文控制在 500 行以内；更长的内容拆进参考文件，按需加载。- Skills 不跨面同步。上传到 claude.ai 的 Skill 不会出现在 API 或 Claude Code 里，反过来也一样。
加载到底怎么发生：三个层级
Anthropic 把 Skills 设计成”用不到时几乎零成本”。截至 2026 年 6 月，文档把加载分成三层：
| 层级 | 加载什么 | 什么时候 | token 成本 |
|---|---|---|---|
| 1. 元数据 | YAML 头里的 name + description | 始终，启动时 | 每个 Skill 约 100 token |
| 2. 指令 | 完整的 SKILL.md 正文 | Skill 被触发时 | 约 5k token 以内 |
| 3. 资源 | 打包的参考文件、脚本 | 仅当 Claude 去读/跑它们时 | 实际无上限（用到前为零） |
所以你可以装几十个 Skill 也不撑爆上下文：平时 Claude 只知道每个 Skill 存在、以及什么时候该用。正文和 reference/ 里的文件一直待在文件系统上，直到一次匹配把它们用 bash 拉进来。脚本更省——Claude 直接跑，只有输出进上下文，源码永远不进。
实际后果是：你的 Skill 的生死，押在头部那约 100 token 上。description 没有发出正确的触发信号，Claude 就到不了第 2 层，你那段写得再漂亮的 instructions 也是隐形的。
精确的约束（2026 年 6 月）
这些是 Anthropic Agent Skills 文档里的校验规则，不是民间传说：
name：最多 64 字符；只能是小写字母、数字、连字符；不能含 XML 标签；不能含保留词 “anthropic” 或 “claude”。Anthropic 建议用动名词形式，如processing-pdfs、analyzing-spreadsheets。description：非空，最多 1024 字符，不能含 XML 标签，要用第三人称写。必须同时说清楚它做什么、以及什么时候用。SKILL.md正文：控制在 500 行以内才稳；超出的拆成单独文件，从正文一层引用。
第三人称这件事比看上去重要。描述会被原样塞进系统提示，所以 “I can help you process Excel files” 或 “You can use this to…” 会造成人称冲突，伤害命中率。要写成 “Analyzes Excel spreadsheets, creates pivot tables, generates charts.”
一步一步：做一个真能触发的 Skill
- 先手搓一遍。在普通 Claude 对话（或一个 Claude Code 会话）里把任务跑到 prompt 稳定为止。手搓不出来，就打包不出来。
- 名字写动作，不写主题。用动名词形式：
summarizing-transcripts，别叫meeting-stuff。控制在 64 字符内。 - 描述写成”做 X。用户在 [具体触发/场景] 时使用”。直接抄 Anthropic 自己的范式——他们的 PDF Skill 是这么写的：
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.把用户真会打出来的关键词原样塞进去。 - 正文像写新人手册：角色、期望输入、步骤、输出格式、拒绝规则。默认 Claude 已经很聪明——只补它不知道的东西。控制在 500 行以内。
- 在正文里放一对 2-3 行的输入/输出样例。Anthropic 的编写指南建议用具体样例、少用抽象描述；一对写好的输入/输出，通常比光秃秃的描述更能让 Skill 稳定触发、稳定产出。
- 装到你用的那个面上。claude.ai：设置 > Features，把 Skill 打包成 zip 上传（Pro、Max、Team 或 Enterprise，且开了代码执行）。Claude Code：把文件夹放进
~/.claude/skills/（个人）或.claude/skills/（项目）。API：通过/v1/skills端点上传。 - 用描述里那句原话先测。不触发就是描述没匹配上——先改措辞，别动 instructions。
- 再用你日常会说的那种说法测。如果漏触发，给描述补一两个真用得上的同义词，仍然用第三人称。这一步还不要改正文。
Skill 为什么不触发（以及怎么修）
几乎所有”它从来不触发”的反馈，根子都在头部，不在模型。
- 描述太空。
Helps with documents没给 Claude 任何可匹配的东西。修法：写清动作加上字面触发词。Anthropic 自己的说法是：一个具体、可触发的描述，是触发率最大的那根杠杆。 - 写成了主题而非触发条件。
About meetings描述的是一个领域，不是一个时刻。修法：Summarizes meeting transcripts into bullets and action items. Use when the user pastes a transcript and asks for a summary. - 用了第一/第二人称。
I can help you...和系统提示打架。修法：改写成第三人称。 - 装错了面。 你上传到 claude.ai 却在 Claude Code 里测，或在 Claude Code 里做了却指望它出现在 API 上。Skills 不同步；每个面单独装。
- 两个 Skill 在抢。 描述重叠时，通常靠扔硬币赢一个。修法：把描述写到互不重叠——写清各自管什么、不管什么。
- 触发条件埋进了正文。 edge case 塞进正文不改变它会不会触发；只有头部能改变。正文保持精简，触发词放在描述里。
第一次跑的练习
- 挑你每周最小的那件事做一个 Skill——比如
summarizing-transcripts：把转录整理成 5 条要点和 3 条 action item。 - 一周里用不同输入跑 5 次。每次记成自动触发、点名调用、还是漏触发。
- 5 次以后只改
description，不动正文。收紧触发词通常就是把自动触发率拉上去的那一下。 - 把 Skill 交给一位同事（要给他重新上传一份；claude.ai 的 Skill 是按用户来的，不会自动共享），让他不经指导直接用。他触发不出来，说明描述太”自己人”了。
质量检查
- 描述里那句自然说法能触发吗？不能就是这句话的 bug。
- 输出形状跨次稳吗？产物每次都不一样形状，那还是个 prompt，不是 Skill——往正文里加模板或一对样例。
- 在相邻但不该触发的请求上它能忍住吗？过度触发跟漏触发一样快地消耗信任。
推荐流程
挑一个高频任务 → 手搓到 prompt 稳定 → 描述按”做 X。用户在 Y 时使用”的第三人称句式写，塞进字面关键词 → prompt 贴成正文，配一对样例 → 装到你的面上 → 先测原句，再测一种说法 → 每周看触发率，先调描述。
FAQ
- Claude 怎么判断要不要触发一个 Skill？ 它会读每个已装 Skill 的
name+description（启动时已预载进系统提示），拿去匹配你的消息。一个具体、含关键词、第三人称的描述是决定性因素；空描述基本不触发。 - 一个 Skill 的精确限制是什么？ 截至 2026 年 6 月：
name≤ 64 字符（小写、数字、连字符；不含 “anthropic”/“claude”）；description≤ 1024 字符、非空、无 XML 标签；SKILL.md正文保持在 500 行以内。 - 能不能按名字强制调？ 在 Claude Code 里可以显式调用一个 Skill；在 claude.ai 里，消息里点名 Skill 名字会强烈偏向选它。适合测 instructions、也适合那种你希望用户主动调的 Skill，但日常你要的是靠描述自动触发。
- Skills 在 claude.ai、Claude Code、API 之间同步吗？ 不同步。每个面都是独立的——用到哪个就往哪个装。claude.ai 的 Skill 按用户走；API 的 Skill 是工作区共享；Claude Code 的 Skill 在你的文件系统里。
- 同一条消息会触发两个 Skill 吗？ 通常只赢一个。描述重叠会导致扔硬币；把描述写成互不重叠，写清各自管什么、不管什么。
- 参考文件和脚本放哪？ 打包进 Skill 文件夹，从
SKILL.md一层引用。它们只在 Claude 去读时才加载，所以一个 Skill 可以带很大的文档或数据集，平时零成本。
相关
- Claude Projects —— 把 Skill 钉到工作区，获得持续的团队上下文
- Claude Code skills 指南 —— 终端工作流里基于文件系统的那一套
- Claude prompt 实操技巧 —— 打包之前先把那条稳定 prompt 写好
- Claude 新手指南
- 官方参考：Anthropic Agent Skills 概览 与 Skill 编写最佳实践