我第一次研究 Claude Skills 时，最大的误判是：这不就是一份写得更长的提示词吗？
真用起来才发现，两者差得挺远。
普通提示词解决的是“这一次怎么做”，Skills 解决的是“以后遇到这类任务，都按什么方法做”。它可以把操作步骤、项目规范、参考资料、模板和脚本装进一个文件夹，在任务匹配时再交给 Claude 使用。
如果你经常重复粘贴同一套要求，或者每次都要提醒 Claude“先检查字段，再运行脚本，最后验证结果”，这类内容就很适合做成 Skill。
本文所说的 Claude Skills，主要指 Anthropic 官方的 Agent Skills 体系，实操部分以 Claude Code 为主。
Claude Skills 到底是什么
一个 Skill，可以理解成发给 Claude 的“岗位操作手册”。
它至少包含一个 SKILL.md 文件，还可以带上脚本、模板、案例和参考文档。例如：
reviewing-content/
├── SKILL.md
├── references/
│ ├── style-guide.md
│ └── fact-check-list.md
└── scripts/
└── check_links.py
这里面各部分分工很明确：
SKILL.md：告诉 Claude 什么时候启用，以及具体怎么做。references/：存放较长的规范、知识和案例。scripts/：处理需要稳定复现的操作，例如校验格式、检查链接。- 模板文件：约束最终交付物的结构。
说白了，Skill 不是让 Claude 临场发挥得更花，而是减少它每次从头猜流程。
Skills、提示词和 MCP 有什么区别
这几个概念经常被混在一起，我一般这么区分：
| 方式 | 主要解决的问题 | 适合场景 |
|---|---|---|
| 普通提示词 | 这一次要怎么回答 | 临时任务、一次性修改 |
| Skills | 同类任务长期按什么流程执行 | 写作规范、审查流程、部署步骤 |
| MCP | Claude 能连接和调用什么外部能力 | 数据库、业务系统、搜索服务 |
| Subagent | 是否需要一个独立角色处理子任务 | 并行研究、代码审查、专项分析 |
| Hooks | 某个事件发生时必须执行什么动作 | 提交前检查、工具调用审计 |
Skill 可以指导 Claude 使用 MCP 或脚本，但它本身不等于一个外部工具。
打个比方，MCP 像给工位接上打印机，Skill 则是告诉新同事：哪些文件要打印、用什么纸、打印后由谁检查。
Claude 为什么不会一次加载所有内容
Skills 有一个很实用的设计，叫渐进式加载。
Claude 通常分三层读取：
- 第一层是元数据：启动时只看到 Skill 的名称和描述，用来判断是否匹配任务。
- 第二层是主说明：任务匹配后，再读取
SKILL.md正文。 - 第三层是扩展资源：只有确实需要时，才读取参考文件或运行脚本。
这也是 Skills 和超长系统提示词的关键区别。
你可以安装不少 Skills，但只要没有触发，通常只有简短的元数据进入上下文。真正占篇幅的流程和资料，会等任务需要时再加载。
不过别因此就往 SKILL.md 里塞一整本手册。官方建议保持简洁，正文接近 500 行时，就该考虑拆成独立参考文件了。
从零创建第一个 Skill
下面做一个“技术文章审校”Skill。它负责检查事实、结构和风险表述。
先在项目中创建目录：
mkdir -p .claude/skills/reviewing-content
然后新建：
.claude/skills/reviewing-content/SKILL.md
写入以下内容：
---
name: reviewing-content
description: Reviews technical articles for factual accuracy, structural clarity, terminology consistency, and unsupported claims. Use when the user asks to review, audit, fact-check, or polish a technical article.
---
# Reviewing Content
## Workflow
1. Read the complete article before editing.
2. Separate factual errors from stylistic suggestions.
3. Mark claims that require a source instead of guessing.
4. Check terminology consistency throughout the article.
5. Preserve the author's original position unless it is factually wrong.
6. Review the revised version against the checklist before delivery.
## Output
Return the result in three parts:
- Critical factual issues
- Recommended revisions
- Revised article
If evidence is insufficient, write “needs verification” and explain what source is missing.
保存后，在该项目中启动 Claude Code，输入：
帮我审校这篇技术文章，重点检查没有依据的结论。
如果描述命中了任务，Claude 会自动加载这个 Skill。也可以直接输入：
/reviewing-content
手动调用。
需要所有项目都能使用，可以把它放在个人目录：
~/.claude/skills/reviewing-content/SKILL.md
需要团队共用，就放在项目的 .claude/skills/ 中，并随代码仓库一起提交。
description 比正文更容易写坏
我见过不少 Skill，正文写得很细，结果就是不触发。问题通常不在流程，而在 description。
描述必须同时回答两件事：
- 这个 Skill 能做什么？
- 用户在什么情况下需要它？
下面这种描述太模糊：
description: Helps with content.
Claude 很难判断“content”到底指写作、审校、排版，还是内容分析。
更合适的写法是：
description: Reviews technical articles for factual accuracy and unsupported claims. Use when the user asks to review, fact-check, audit, or polish technical content.
名称也别叫 helper、tools 这种宽泛词。一个目录里装了几十个 Skill 后，这类名字看着就头疼。
按照 Agent Skills 通用规范，name 最长为 64 个字符，只能使用小写字母、数字和连字符。description 不能为空，最长为 1024 个字符，而且建议使用第三人称表述。
流程该写多细
这件事没有统一答案，要看操作出错后的代价。
如果任务允许多种做法，比如文章点评，可以给 Claude 较大的判断空间：
1. 分析文章的目标读者。
2. 检查结构和论证。
3. 根据上下文提出修改建议。
如果任务容易出错，比如数据库迁移，就应该把顺序和命令钉死：
1. 先创建备份。
2. 运行指定迁移脚本，不得增加参数。
3. 执行验证脚本。
4. 验证失败时停止，不得继续部署。
我的判断方式很简单：像在空地上走路，可以只给方向；像在窄桥上推设备，就要把每一步写清楚。
对格式校验、批量处理和数据转换这类任务，与其写十段说明，不如提供一个经过测试的脚本。脚本负责稳定执行，Claude 负责判断什么时候运行。
把长资料拆出去
如果一个 Skill 同时覆盖选题、写作、审校和发布，不要把所有内容堆进主文件。可以改成：
content-workflow/
├── SKILL.md
├── references/
│ ├── topic-selection.md
│ ├── writing-style.md
│ ├── review-checklist.md
│ └── publishing-rules.md
└── templates/
└── article-template.md
在 SKILL.md 里说明读取条件：
- 选题任务：读取 references/topic-selection.md
- 写作任务：读取 references/writing-style.md
- 审校任务：读取 references/review-checklist.md
- 生成成稿：使用 templates/article-template.md
参考文件最好都从 SKILL.md 直接链接，不要再让参考文件跳到第三层、第四层。层级太深时，Claude 可能只预览一部分内容，真正关键的规则反而没读全。
怎么测试一个 Skill 是否真有用
我不建议写完看一眼格式就算交工。至少准备三类测试：
- 应该触发：用户的表达与描述高度匹配。
- 不该触发：任务相近，但不需要这套流程。
- 边界情况：信息不完整、文件缺失或要求互相冲突。
测试时重点看四件事：
- Skill 是否在正确的任务中触发。
- Claude 有没有漏掉关键步骤。
- 输出格式是否稳定。
- 失败后是否按规定停止或重新验证。
最好再做一次无 Skill 对照测试。如果加了 Skill 后，结果和原来没明显区别，说明里面可能只是写了 Claude 本来就知道的常识。
真正有价值的内容，通常是项目特有的字段定义、固定检查顺序、禁用操作、交付模板和团队经验。
通过 Claude API 使用 Skills
在 Claude API 中，Skills 要和 Code Execution 工具配合使用。调用时通过 container.skills 指定 Skill：
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="YOUR_MODEL",
max_tokens=4096,
container={
"skills": [
{
"type": "custom",
"skill_id": "YOUR_SKILL_ID",
"version": "latest"
}
]
},
messages=[
{
"role": "user",
"content": "Review this technical article."
}
],
tools=[
{
"type": "code_execution_20250825",
"name": "code_execution"
}
]
)
按照官方当前文档，一次请求最多可配置 20 个 Skills，自定义 Skill 未压缩总上传体积要小于 30 MB。
开发阶段可以使用 latest 方便迭代。生产环境更适合固定版本号，否则工作区里有人发布了新版，线上行为可能跟着变化。
还要注意，API 的 Skills 运行环境不能联网，也不能在运行时安装新包。依赖外部接口或冷门库的流程，不能只在本机跑通就算完成。
安全问题别放到最后才想
Skill 可以包含指令、脚本和外部资料，权限并不低。
我的原则是把它当软件安装包审，而不是当一篇 Markdown 看：
- 检查脚本是否读取了无关文件。
- 检查是否存在异常网络请求。
- 检查外部链接是否可能返回动态指令。
- 限制可以使用的工具和目录。
- 生产环境固定版本并保留变更记录。
- 不直接安装来源不明的 Skill 压缩包。
特别是能访问业务数据、凭据或生产环境的 Claude，Skill 写错最多是事故，Skill 被恶意设计就不只是事故了。
最后说两句
Claude Skills 最适合沉淀的，不是百科知识，而是那些“我们每次都这样做，但总有人忘”的流程。
别一上来就造一个覆盖全公司的万能 Skill。先从一个高频小任务开始：整理周报、检查代码变更、审校文章，或者验证部署结果。
跑三次，记录 Claude 在哪里误解；再改描述、补步骤、加校验。等它在不同输入下都能稳定工作，再考虑拆资料、加脚本和组合多个 Skills。
Skill 的价值不在文件夹有多大，而在下一次遇到同类任务时，你不用从第一句话重新教。
