Claude Code Skills 完全指南：Anthropic 内部数百个 Skills 用下来的经验总结

大多数人以为 Claude Code 的 Skills 只是 Markdown 文件。

这个误解，让他们少用了 Skills 90% 的威力。

Anthropic 工程师内部有数百个 Skills 在积极使用中。他们公开了两份核心经验材料：一篇是对内部 Skills 库的系统性梳理，另一份是官方 Skilljar 课程”Agent Skills”的核心提炼。我把两份材料最有价值的内容整合起来，加上自己的实践，整理成这篇完整指南。

读完你会明白：Skills 到底是什么，和 MCP 有什么本质区别，有哪些类型，以及怎么写才有用。

---

Skills 的本质：不是文件，是文件夹

Skills 最常见的误解是”它就是个 Markdown 文件”。

实际上，Skills 是一个文件夹，可以包含：

• 脚本（Python、Shell、JS）
• 参考资料（代码片段、API 文档）
• 配置文件（config.json）
• 数据资产（模板、示例输出）
• 记忆存储（日志文件、SQLite 数据库）

Agent 能发现、探索并操作这整个文件夹结构。

这意味着你可以把整个工具链打包进一个 Skill，让 Claude 像使用工具箱一样使用它，而不只是读一段文字说明。

---

Skills vs MCP：大脑和手脚的区别

很多人搞不清楚 Skills 和 MCP 的边界，认为两者都是”扩展 Claude 能力”的工具，没有本质差异。

一个比喻能帮你厘清：

你雇了一位新员工。给他配发工作账号（GitHub、Slack、数据库访问），这是 MCP，是”手脚”，让他能操作外部系统。但仅有账号不够，你还要给他一本操作手册，说明公司流程、哪些事要怎么做、哪些坑不能踩，这是 Skills，是”大脑”，是 SOP。

两者的核心差异：

MCP 是手脚：本质是工具连接，解决”能做什么”。GitHub MCP、Slack MCP、数据库连接，全局生效，持续运行。

Skills 是大脑：本质是流程知识，解决”怎么做”。代码审查 SOP、部署流程、内部规范，按需激活，针对性强。

MCP 解决的是”连接到哪里”的问题，Skills 解决的是”到了那里该怎么做”的问题。

两者组合才能发挥最大效果。能力和流程的相乘，而不是相加。

---

为什么需要 Skills？三个核心瓶颈

没有 Skills，AI 辅助开发通常卡在三个地方：

上下文盲区：Claude 不了解你的内部库、私有 API、团队规范。每次都要重新解释，而且解释了也可能理解偏差。

流程真空：Claude 很擅长单点任务，但复杂工作流涉及多个步骤、多个工具、多个决策节点。没有 Skills，Claude 只能靠即兴发挥，每次输出质量不稳定。

执行焦虑：涉及高风险操作（数据库变更、生产部署、批量文件修改），你不敢放手让 Claude 自主执行，因为不确定它会不会漏掉关键步骤。

---

9 种 Skills 类型

Anthropic 整理内部 Skills 后，发现它们自然聚集为 9 个类别。

1. 参考技能（Reference Skills）

教 Claude 如何正确使用某个库、CLI 或 SDK。不是给 Claude 看官方文档，而是把你踩过的坑、边缘情况、内部命名规范全部提炼进去。

示例：

• billing-lib：内部计费库的雷区清单
• frontend-design：提升 Claude 的设计品味，避免千篇一律的 Inter 字体加紫色渐变

核心价值：突破 Claude 的默认认知盲区。

2. 验证技能（Validation Skills）

告诉 Claude 如何测试和验证代码是否真的跑通了。Anthropic 的说法是”花一周时间让工程师优化验证技能非常值得”。

技巧：让 Claude 录制输出视频，或在每一步强制执行程序化断言。

示例：

• signup-flow-driver：无头浏览器跑完注册→邮箱验证→引导入职全流程，每一步断言状态
• checkout-verifier：用 Stripe 测试卡驱动结账，验证发票状态正确

核心价值：闭环验证，让 Claude 真正对结果负责。

3. 数据技能（Data Skills）

连接数据和监控系统。包含访问凭证、特定仪表盘 ID、常用查询指南，让 Claude 能直接查生产数据。

示例：

• funnel-query：“哪些事件串联查看注册→激活→付费”，包含实际表名
• grafana：数据源 UID、集群名称和问题到仪表盘的映射表

核心价值：让 Claude 变成真正懂你业务数据的分析师。

4. 自动化技能（Automation Skills）

把重复工作流变成一条命令。

示例：

• standup-post：汇总工单追踪、GitHub 活动、Slack 历史，生成格式化日会报告，只显示变化部分
• weekly-recap：合并 PR + 关闭工单 + 部署记录，一键生成周报

核心价值：把你每天重复三遍的操作压缩成零成本。

5. 脚手架技能（Scaffolding Skills）

为代码库中的特定功能生成框架模板。

示例：

• new-framework-workflow：脚手架一个带注释的新服务或处理器
• create-app：新建内部应用，预设认证、日志和部署配置

核心价值：统一工程规范，新人上手速度翻倍。

6. 审核技能（Review Skills）

在组织内执行代码质量控制。建议作为 Git Hook 或 GitHub Action 自动触发。

示例：

• adversarial-review：生成新视角子代理进行批判，实施修复，直到问题只剩细枝末节
• code-style：强制执行 Claude 默认表现不佳的代码风格

核心价值：把代码审查标准系统化，不再靠人肉盯。

7. 工作流技能（Workflow Skills）

帮助获取、推送和部署代码的端到端流程。

示例：

• babysit-pr：监控 PR，重试不稳定 CI，解决合并冲突，启用自动合并
• deploy-service：构建→冒烟测试→逐步流量发布并比对错误率→回归时自动回滚

核心价值：把部署变成无聊的例行任务，而不是提心吊胆的操作。

8. 调查技能（Investigation Skills）

接受症状（Slack 报障、告警、错误特征），跨工具调查，生成结构化报告。

示例：

• oncall-runner：获取告警→检查常见问题→格式化发现
• log-correlator：根据请求 ID 从所有系统提取匹配日志

核心价值：on-call 的时候不用自己一个系统一个系统去翻。

9. 维护技能（Maintenance Skills）

执行例行运维任务，部分包含破坏性操作，需要保护措施。

示例：

• resource-orphans：查找孤儿 Pod 或 Volume，通知 Slack，等待确认，再级联清理
• cost-investigation：“为什么存储或出口费用暴增”，附带具体桶和查询模式

核心价值：高风险操作标准化，减少人为失误。

---

一个 Skill 的内部结构

每个 Skill 的核心文件是 SKILL.md，顶部是 YAML frontmatter，下面是内容主体。

YAML frontmatter 四个关键字段：

---
name: deploy-service
description: 当需要部署服务到生产环境时触发。覆盖构建、冒烟测试、流量切换、回滚全流程。
disable-model-invocation: false
allowed-tools:
  - Bash
  - Read
  - Write
---

description 字段特别重要，不是摘要，是触发条件。Claude 启动时会扫描所有 Skills 的 description，判断”是否有合适的 Skill”。写”这是一个部署工具”远不如写”当需要部署服务、执行发布流程时触发”有效。

disable-model-invocation: true 适合高危 Skill，强制人工确认后才执行，而非 Claude 自主判断。

allowed-tools 限制这个 Skill 能使用的工具范围，对需要控制权限边界的场景很有用。

一条实用原则：SKILL.md 保持在 500 行以内。超出的内容拆分到子文件，在主文件里用相对路径引用。文件系统本身就是你的渐进式揭示机制，Claude 会在需要时去读对应文件。

---

制作优质 Skills 的 10 个秘诀

秘诀一：聚焦高信号上下文

Claude 对通用编程已经知道很多了。你的 Skill 应该聚焦在”Claude 不知道的部分”——你们团队的内部规范、历史决策、特有工具的奇怪行为。

秘诀二：捕捉”坑点”

Skills 中价值最高的内容是”踩过的坑”。每次 Claude 因为某个原因失败，把这个坑写进 Skill。随着时间积累，Skills 会越来越智能。

秘诀三：用好整个文件系统

不要把所有内容塞进一个 Markdown 文件。用文件夹结构来组织，告诉 Claude “我的 Skill 里有这些文件”，它会在需要时自动读取。这是渐进式揭示的核心思路。

秘诀四：指令要灵活，不要太具体

Skills 是高度可复用的。提供所需的信息框架，留出空间让 Claude 灵活处理不同情况。

秘诀五：用 config.json 处理交互配置

某些 Skills 需要用户配置（比如发到哪个 Slack 频道）。把配置存在 config.json 里，未配置时让 Claude 向用户询问。

秘诀六：让 Skills 有记忆

用追加日志文件、JSON 文件或 SQLite 数据库让 Skills 记住历史状态。例如 standup-post Skill 保留 standups.log，下次执行时 Claude 对比历史，只报告有变化的内容。

注意：用 ${CLAUDE_PLUGIN_DATA} 作为持久化存储路径，避免 Skill 升级时数据被清空。

秘诀七：直接给 Claude 代码

把可复用的函数、辅助库、脚本直接放进 Skill 文件夹，让 Claude 可以调用。这样 Claude 只需要专注于”如何组合这些工具解决问题”。

秘诀八：动态注入运行时上下文

Skills 不仅能提供静态知识，还可以在每次执行时动态注入实时信息。语法是 ! 命令：

当前 git 状态：
! git log --oneline -10
! git diff --stat HEAD~1

$ARGUMENTS 用于接收调用时传入的参数。例如 /deploy-service production 中，$ARGUMENTS 的值就是 production。

秘诀九：用 context: fork 启动子代理

Skills 内部可以通过 context: fork 启动独立的子代理并行处理任务。典型用法是代码审查：fork 出多个子代理分别从架构、安全、性能三个维度并发审查，最后汇总结果。

秘诀十：用动态钩子控制行为边界

Skills 可以包含只在被调用时激活的钩子。最好的例子：

• /careful：在 PreToolUse 钩子里阻止 rm -rf、DROP TABLE、kubectl delete
• /freeze：阻止任何非指定目录的写操作

---

真实案例：代码 CR Skill 是怎么工作的

触发条件：用户执行 /cr 或说”帮我审查这个 PR”。

执行流程分四个阶段：

第一阶段：评估规模

Skill 先运行脚本统计改动行数。小于 200 行，自动进入 AI 审查；200 到 500 行，提示用户建议拆分；超过 500 行，建议分批审查，人工确认后继续。

规模评估让 Claude 能在开始前就知道”这是一个小改动还是大重构”，输出的审查深度完全不同。

第二阶段：自动化检查

在进入 AI 分析前，先跑确定性工具：lint 检查、类型检查、单元测试。把确定性工作交给确定性工具，把判断性工作留给 AI。

第三阶段：多维度并发审查

通过 context: fork 启动三个并发子代理：

• 子代理一：架构和设计层面，是否引入不必要的复杂度
• 子代理二：安全性，注入风险、权限边界、敏感数据处理
• 子代理三：性能，N+1 查询、不必要的同步调用、内存泄漏风险

三个维度并发跑，速度快，而且各子代理的审查视角纯粹，不会产生偏见。

第四阶段：生成结构化报告

最终汇总成统一格式的审查报告：问题按严重程度分级（阻断、建议、细节），每条问题附带代码位置、原因说明、改进建议。

一个原本需要高级工程师花 30 到 45 分钟的 PR 审查，压缩到几分钟，而且覆盖维度比人工更全面。

---

怎么开始

按这个优先级来：

第一步：识别你团队最痛的重复工作，从「自动化技能」入手，效果最直接。

第二步：找出 Claude 最常犯错的地方，建一个「参考技能」，把坑点列进去。

第三步：为核心业务流程建「验证技能」，让 Claude 能自我检验输出是否正确。

---

有一个公式值得记住：能力 × 流程 = 真正的 AI 生产力。

MCP 给了 Claude 访问工具的能力，但能力本身不等于效率。Skills 把你的团队流程注入进去，才完成了这个乘法。缺了任何一边，结果都会大打折扣。

随着时间积累，你的 Skills 库会成为团队最有价值的 AI 资产。不是因为它用了最新的模型，而是因为它沉淀了你们团队独有的经验，这是任何通用 AI 替代不了的部分。

---

基于 Anthropic 工程团队发布的 Claude Code Skills 实践经验整理，结合个人实践补充。