Claude Code Skills 深度指南：Anthropic 内部都在用的实战经验

正文

Anthropic 内部在用数百个 Claude Code Skills，Thariq 这篇文章把他们踩过的坑、总结出的套路全写出来了。不是官方文档那种平铺直叙，是真正用过之后的经验。

Claude Code 的 Skills 功能火了很久，但大多数人只停在"会用"这一层。会写一个 SKILL.md、会把它放到 .claude/skills 目录——然后就没了。

Anthropic 内部用了数百个 Skills，工程师 Thariq 最近把这段经验写成了长文。读下来，跟自己摸索的那套有挺多不一样的地方。

Skills 不是 Markdown 文件，是文件夹

这是理解 Skills 的第一个关键转变。

很多人觉得 Skill 就是写一个 SKILL.md 文件，告诉 Claude 要做什么。Thariq 说，这是最常见的误解。Skills 是文件夹，不是文件。文件夹里可以放脚本、资产文件、引用文档、配置……整个文件系统都是上下文工程的一部分。

把 Skills 当文件夹来设计，而不是当 Markdown 来写——这个思路一转，能做到的事就完全不同了。

举个例子：如果你的 Skill 最终要输出一个 Markdown 报告，可以在 assets/ 目录里放一个模板文件，让 Claude 直接复制和填充，而不是让它凭空生成格式。如果有函数签名和使用示例，可以单独放到 references/api.md，需要的时候 Claude 自己去读。

这叫"渐进式披露"——告诉 Claude 有哪些文件，它会在合适的时机去读，而不是一次全部塞进上下文里。

9 类 Skills，逐一拆解

Thariq 团队把内部所有 Skills 梳理归类，发现基本上能分成 9 类。最有意思的地方是，不少工程师写了一堆 Skills，但只覆盖了其中 2-3 类——有些场景根本没想到可以用 Skill 来解决。

① 知识 / 参考类（Knowledge & Reference）

告诉 Claude 如何正确使用内部库、CLI 或 SDK。适合内部库，也适合 Claude 经常用错的外部库。这类 Skill 通常包含一个参考代码片段目录，以及一份 Claude 写这类代码时要主动避开的坑列表。

原文案例：

• billing-lib — 内部计费库的边界情况、各种 footgun
• internal-platform-cli — 内部 CLI 的每个子命令，附带"什么时候用哪个"的示例
• frontend-design — 让 Claude 更好地理解你的设计系统

② 验证类（Verification）

描述如何测试或验证代码是否正确。通常搭配 Playwright、tmux 等外部工具做实际验证。Thariq 专门强调：让工程师花一周时间把验证 Skills 做好，是值得的投资。可以考虑让 Claude 录制操作视频，或者在每一步用断言验证程序状态——这些都可以通过 Skill 里的脚本来实现。

原文案例：

• signup-flow-driver — 自动跑注册 → 邮箱验证 → onboarding 全流程，每步断言状态
• checkout-verifier — 用 Stripe 测试卡驱动结账 UI，验证发票状态
• tmux-cli-driver — 专门用于需要 TTY 的交互式 CLI 测试

③ 数据访问类（Data Access）

连接数据和监控系统。通常包含带凭证的数据获取库、仪表盘 ID 等，以及常见查询工作流说明。

原文案例：

• funnel-query — "我该 join 哪些事件才能看到 注册→激活→付费 的路径"，附带真实的 userid 表
• cohort-compare — 比较两个用户群的留存率或转化率，标记统计显著差异，链接到分群定义
• grafana — 数据源 UID、集群名称、"症状 → 对应仪表盘"查找表

④ 自动化工作流类（Automation）

把重复操作压缩成一条命令。指令通常比较简单，但可能依赖其他 Skills 或 MCP。Thariq 提示：把每次执行的结果存进日志文件，能帮模型在多次执行之间保持一致性，也方便它反思"上次干了什么"。

原文案例：

• standup-post — 汇总工单系统、GitHub 活动、前一天 Slack 内容，生成格式化日报，只写增量变化
• create--ticket — 执行字段 schema 校验（有效枚举值、必填字段），附带创建后工作流（通知审查人、同步 Slack）
• weekly-recap — 已合并 PR + 已关闭工单 + 部署记录 → 格式化周报

⑤ 脚手架类（Scaffolding）

为代码库的特定模块生成框架样板。这类 Skill 特别适合当你的脚手架里有自然语言要求、无法完全用代码表达的时候，可以配合可组合脚本一起用。

原文案例：

• new--workflow — 带注解的新服务/工作流/处理器脚手架
• new-migration — 数据库迁移文件模板，附带常见踩坑提示
• create-app — 预置好认证、日志、部署配置的内部应用模板

⑥ 代码审查类（Code Review）

执行代码质量检查。可以包含确定性脚本或工具以保证可靠性，也可以放到 Git Hook 或 GitHub Action 里自动触发。

原文案例：

• adversarial-review — 起一个独立子 agent 专门批评，实施修复，反复迭代直到问题只剩小细节
• code-style — 强制代码风格，尤其是 Claude 默认不会做好的那些
• testing-practices — 描述如何写测试、测什么

⑦ 部署类（Deploy）

拉取、推送、部署代码。这类 Skill 可能会引用其他 Skills 来收集数据。

原文案例：

• babysit-pr — 监控 PR → 重试 flaky CI → 解决合并冲突 → 开启自动合并
• deploy- — 构建 → 冒烟测试 → 灰度流量切换（持续对比错误率）→ 回归时自动回滚
• cherry-pick-prod — 独立 worktree → cherry-pick → 冲突处理 → 按模板提 PR

⑧ 调试类（Debug）

定位问题、收集诊断信息。日志文件路径、调试端口、集群 SSH 入口……这些都可以放进去。

原文案例：

• debug-java — JVM 调试端口、thread dump 命令、heap dump 触发方式
• debug-node — Node 调试端口、heap snapshot、 Flame graph 生成
• debug-k8s — kubectl 常用命令、logs 的 tail 技巧、"事件 → Pod 状态 → 资源配置"排查路径

⑨ 运维类（Operational）

线上的开关控制、数据修复、紧急回滚。操作生产环境前需要额外校验，所以这类 Skill 往往会引用其他 Skills 做双重确认。

原文案例：

• critical-toggle — 线上 Feature Flag 开关，带二次确认和审计日志
• urgent-rollback — 回滚步骤 + 通知 + 事后复盘模板
• data-repair — 修复用户数据，按 userid 批量处理，附带 dry-run 模式和修复前后对比

Claude Code Hooks：让 Skills 更精准

除了 Skills 本身，Claude Code 还有 Hooks 可以用。Thariq 推荐了几个特别实用的：

• /confirm — 让 Claude 在执行高风险操作前暂停，比如 rm、DROP TABLE、强制推送
• /review — 触发代码审查模式，适合已经写完代码但想再过一遍的场景
• /careful — 禁止 rm -rf、DROP TABLE、强制推送、kubectl delete，触碰生产环境时用
• /freeze — 限制只能在特定目录下修改文件，调试时防止 Claude 误改不相关代码

如果这类 Hook 全局常驻，会烦死人。作为 Skill 按需激活，刚好。

在团队里分发 Skills

两种方式：把 Skills 提交到 repo 的 .claude/skills 目录，或者建内部插件市场。

前者适合小团队，简单直接。但每个 Skill 都会给模型上下文加一点负担，规模大了就需要插件市场——让团队自己选安装哪些。

Anthropic 内部的做法：没有中心化审核团队，而是靠自然传播。有好 Skill 就发到 GitHub 沙盒目录，在 Slack 里分享，自然获得使用和反馈。等它有了足够的关注度，技能作者自己提 PR 把它并入市场。

注意：坏的或者重复的 Skills 很容易冒出来，上线前做好筛选机制很重要。

Skills 之间可以有依赖，比如"CSV 生成 Skill"依赖"文件上传 Skill"。目前没有原生的依赖管理，但可以在 Skill 里直接引用其他 Skill 的名字，模型会在对方安装的情况下调用它。

想了解 Skill 的实际使用情况？Thariq 提到他们用 PreToolUse hook 记录公司内部每个 Skill 的调用日志，这样就能找出最受欢迎的 Skill，或者发现某个 Skill 触发频率远低于预期——这通常说明 description 没写好。

写在最后

这篇文章总结得太到位了，推荐直接去看 Thariq 的原始推文。以下是核心要点：

• 9 类 Skills ：知识、验证、数据访问、自动化、脚手架、代码审查、部署、调试、运维——逐一检查有没有盲点
• 文件夹思维 ：脚本、模板、引用文档都可以放进去，渐进式披露给 Claude
• Gotchas 优先 ：记录 Claude 真正踩过的坑，比通用说明更值钱，随时更新
• description 是触发器 ：写"什么时候用"而不是"能做什么"
• 给 Claude 代码 ：helper functions 比详细文字指令更能解放 Claude 的决策带宽
• 加上记忆 ：用日志文件存历史，让 Skill 跨会话保持连续性
• 验证 Skills 值得专项投入 ：让 Claude 能自己校验输出，质量差别很大