Claude 内部工程师总结的Skills经验全在这了

先搞清一个概念：Skill 是文件夹不是文件

很多人以为 Skill 就是一个 Markdown 文件，写点提示词让 Claude 照着干。

Thariq 专门纠正了这个误解："A common misconception is that skills are 'just markdown files', but they're folders that can include scripts, assets, data"（常见的误解是 Skill 只是 Markdown 文件，但实际上它们是可以包含脚本、资产、数据的文件夹）

为什么这个区别重要？因为纯 Markdown 提示词只能告诉 Claude "你应该怎么做"，但文件夹结构让 Skill 可以带上 Python 脚本、数据库、配置文件这些"工具"。Claude 不只是读指令然后靠自己发挥，它能直接调用现成的脚本来执行确定性操作。

我自己的推文保存 Skill 里面就有 Python 采集脚本、一个专门记录"哪些推文已经处理过"的小型数据库、还有一个存 API 密钥的配置文件。如果只是一个 Markdown 文件，这些全得靠 Claude 每次临时编写，结果每次都不一样，还经常出错。有了脚本，执行结果就是确定的。

理解了这一点，后面的内容才看得懂。

10 种 Skill 分类，对照一下你缺哪些

Thariq 把几百个 Skills 归了 10 类。他说了一个关键判断标准：最好的 Skill 只属于一个分类，跨多个分类的通常是设计有问题的。

我拿自己的 40 个 Skills 对照了一遍，发现高度集中在"工作流自动化"这一类，验证类和调试类几乎空白。这让我挺意外的。

1. 知识库类：把团队经验变成 Claude 能读取的记忆。比如你们公司的微信支付接口有个隐藏限制文档里没写，写成 Skill 之后 Claude 帮你写支付代码时自动绕开。我的 RSS 简报 Skill 里就有一段专门记 BestBlogs 的链接还原规则，这个坑踩了三次才固化进去。

2. 验证类：让 Claude 自己测自己。用自动化浏览器跑注册流程、用测试卡验证支付。Thariq 说这类 Skill "值得让工程师花一整周打磨"，因为验证质量直接决定 Claude 输出的可靠性。投入产出比极高，写一次用一年。

3. 数据查询类：连接你的数据和监控系统。以前查数据要写 SQL 或者登各种后台，现在对 Claude 说一句"上周注册转付费的转化率是多少"，它自己去查自己算。

4. 工作流自动化类：重复的事情只做一次。自动生成站报、自动写周报。我的整个内容生产线就是这个思路，推文采集、AI 打分、去重、写文章、排版，每一步都是一个 Skill 串起来，四个字就能启动一天的产出。

5. 脚手架类：新项目秒级启动。说一句"新建一个 API 服务"，整个项目骨架秒级生成，连测试文件都给你写好了。

6. 代码质量类：上线前的最后一道关。adversarial-review 这个名字起得好，"对抗审查"，让 Claude 专门找你代码里的安全漏洞、边界情况、性能问题，越刁钻越好。

7. 部署类：从提交到上线全程监控。babysit-pr，"看孩子"，从你提交代码开始 Claude 一直盯着，自动化测试失败了自动修，审查者提意见自动改。你开完会回来发现已经部署了。

8. 调试类：半夜告警不用爬起来。Claude 自动拉日志、关联上下游服务、定位根因，给你一份排查报告，你看一眼就知道要不要紧急处理。

9. 运维类：省钱 + 打扫卫生。云服务用久了到处是忘记删的测试实例，每个月白烧钱。这类 Skill 定期扫一遍帮你找出来。

10. 数据报告类：连上数据源做分析出报告。每月运营报告、同比环比、带图表的那种，Claude 自动拉数据自动算。

踩坑清单是整个 Skill 里信息密度最高的部分

这条让我拍大腿。

Thariq 原话："The highest-signal content in any skill is the Gotchas section."（Skill 里信号最强的内容是 Gotchas 章节。）

Gotchas 直译是"陷阱"，就是踩坑清单：这个 Skill 执行过程中哪里容易翻车、哪些坑已经有人踩过了，全记在这里。

为什么踩坑清单比正文指令更重要？因为 Claude 本身就懂大部分编程知识，你写"用 Python 处理 JSON"它不需要你教。但它不知道你的 JSON 文件里有个字段偶尔会返回空值导致整个流程崩溃，这种只有踩过坑的人才知道的东西，就是踩坑清单的价值。正文指令告诉 Claude "做什么"，踩坑清单告诉它"哪里会翻车"。

Thariq 建议持续更新这个清单，每次遇到新问题就往里加一条。

我回头看自己的 Skills，有些确实写了，比如视频翻译里写了"720p 字号 28、4K 字号 44，不然字太小看不清"，公众号排版里写了"IP 白名单必须更新不然发布直接 403"。

但大部分 Skills 的踩坑清单写得很随意，或者干脆没写。更典型的问题是，我很多踩坑记录存在记忆系统里，但没搬到对应 Skill 里。记忆系统是给我自己看的，踩坑清单是给 Claude 看的，Claude 执行的时候不会翻我的记忆文件。

接下来要做的事很明确：把记忆系统里的踩坑记录按 Skill 归类，一条条搬过去。

description 是触发器不是摘要

大多数人写 description 就像写产品说明书，"这个 Skill 用于将推文内容转换为公众号文章"。准确，但 Claude 不知道什么时候该调用它。

description 应该写成触发条件。好的写法："当用户要求翻译视频、处理字幕、或者提到 YouTube 链接时使用"。烂的写法："这是一个视频翻译工具"。

差距很大。前者告诉 Claude 什么条件下触发，后者只描述了功能。

为什么这件事这么关键？因为 Claude 的工作记忆是有限的，不可能启动时把所有 Skill 的完整内容都读一遍，那样 40 个 Skill 会直接占满大半个脑子，还没开始干活就转不动了。所以 Skills 用的是"按需加载"的机制：启动时每个 Skill 只读名字和 description 这一小段话，被触发后才加载完整内容。

这也意味着 description 是 Claude 在决定"要不要调用这个 Skill"时唯一能看到的东西。写不好，Claude 遇到相关需求时根本想不起来有这个 Skill，等于它不存在。

给 Claude 灵活度，别把指令写死

Thariq 反复强调这条。很多人写 Skill 恨不得每一步都规定死，结果遇到稍微不一样的情况 Claude 就卡住了。

为什么写死反而不好？因为 Skill 是要被反复使用的，每次面对的具体情况都不一样。你把第三步写成"调用 Twitter API 获取推文"，换成一个没有 Twitter 链接的场景，Claude 到第三步就懵了：指令说要调 Twitter API，但这次没有 Twitter 链接，它到底该继续还是报错？更好的写法是"获取原始内容"，Claude 自己判断该用什么方式获取。

我有正反两方面的经验。我的 write-article Skill 用"三阶段协议"：准备期采素材、裸写期不看规则直接写、扫描期只查硬性违规。每个阶段只给目标不给详细步骤，Claude 发挥空间大，质量反而更稳定。

反面的，早期推文保存 Skill 把抓取流程写得特别死，接口格式一变就挂。后来改成"确保推文内容完整保存，包括文本、图片、链接和元数据"，让 Claude 自己选实现方式，稳定性好了很多。

给 Claude 代码而不是自然语言指令

能用脚本实现的就别用自然语言描述。脚本比指令高效得多，执行结果也更确定。

你让 Claude "把日期格式统一" 它可能每次统一的方式都不一样。但如果 Skill 里有一个现成的日期格式化脚本，结果就是确定的。

这背后的原因是：自然语言指令给 Claude 的是"意图"，它需要自己想办法实现，每次的实现路径可能不同。脚本给它的是"工具"，它只需要决定什么时候调用，执行结果是固定的。Skill 的最佳实践是让 Claude 把精力花在组合和决策上，而不是从零实现基础操作。

我的视频翻译 Skill 就是这个思路，字幕分割、时间轴对齐、水印叠加全部用 Python 脚本，Claude 负责调度，脚本负责执行。丢一个 YouTube 链接说"翻译视频"四个字就能出成品。

Skill 可以内置记忆

Thariq 提到 Skill 可以在自己的文件夹里存数据，比如日志文件、数据记录、小型数据库。下次运行时读取历史，就知道上次做到哪了。

为什么 Skill 需要记忆？因为没有记忆的 Skill 每次运行都是从零开始的。我的推文保存 Skill 如果不记录处理过哪些推文，同一条推文会被反复保存。RSS 简报如果不记录推送过哪些文章，读者每天收到一堆重复内容。记忆让 Skill 有了"上下文"，知道上次做到哪了、这次该从哪接着做。

这个我不光在用，而且用得很重。推文保存有数据库防重复，RSS 简报有去重文件，视频翻译有进度文件。甚至做了统一的 Web 管理面板集中管理所有 Skill 的配置。

不过 Thariq 提到一个我没注意的点：Skill 升级时文件夹可能被清空，要把数据存在不会被清掉的路径。这个以后要注意，不然辛苦积累的记忆一次升级就没了。

安全护栏：给 Claude 装一道"动手之前先过审"的机制

这个玩法我之前完全没想到。

Skill 可以注册一种叫 Hooks 的机制，就是在 Claude 动手之前先过一道检查。只在这个 Skill 被调用时才生效，不影响其他场景。

Thariq 举了两个例子：一个叫 /careful，在 Claude 执行命令之前先扫一遍，发现 rm -rf（删除所有文件）、DROP TABLE（清空数据库）、强制推送代码这些危险操作就直接拦住。另一个叫 /freeze，锁定某个目录不让改，防止 Claude 误动关键文件。

为什么 Claude 需要被拦？因为 Claude 执行命令的时候，"删除所有文件"和"列出文件清单"对它来说没有本质区别，都是"用户让我执行的命令"。它不会自己判断一条命令有没有破坏性。安全护栏的作用是在 Claude 动手之前先过一遍规则：这条命令碰了受保护的目录？拦住。包含危险操作？拦住。Claude 继续干活，但危险操作被挡在外面了。

回想起来确实需要，有一次 Claude 帮我调试差点把数据库文件给覆盖了。这个优先级我要提上来。

SKILL.md 是跨平台开放标准

这个很多人不知道。SKILL.md 不是 Claude Code 的私有格式，Cursor、Windsurf、Cline 都支持。你写一次到处能用。

Anthropic 用的词很有意思叫"分布收敛"，意思是各家 AI 编程工具最终会收敛到同一套标准上。所以不用担心被锁定。

两种 Skill 哲学

所有 Skill 可以分成两大类：

能力提升型（Capability Uplift）：让 Claude 能做原来做不了的事，比如连数据库、调外部接口、操作浏览器。没有这类 Skill，Claude 再聪明也只能动嘴不能动手。

偏好编码型（Encoded Preference）：让 Claude 按你的方式做事，比如代码风格、写作规范、命名规则。没有这类 Skill，Claude 每次都用自己的"默认口味"输出，你得反复纠正。

这个分类对你选择"先做哪个 Skill"很有帮助。如果你的痛点是"Claude 做不到某件事"，先做能力提升型的。如果你的痛点是"Claude 能做但做出来的不合我意"，先做偏好编码型的。

我的 40 个 Skills 两种都有。对内容创作者来说，偏好编码型占多数，"按我的方式做"比"做我不会做的事"更重要。但能力提升型才是真正省时间的核心。

对照完了，我要改三件事

第一，补验证类 Skills。至少给每个核心工作流加一个自动检查环节，链接是否有效、图片是否存在、数据是否完整。

第二，把记忆系统里的踩坑记录迁移到各个 Skill 的踩坑清单里。让 Claude 执行的时候直接能看到。

第三，做一个 /careful 级别的安全护栏，保护关键目录和数据库文件。

Thariq 总结的这些经验，没有一条是"哇我从来没想到"的。更多是把模糊的直觉变成了清晰的框架，让你知道自己做对了什么、漏掉了什么。

Skill 的本质就是把你的工作方式变成可复用的代码。你每天怎么干活，把它固化下来，以后不用每次都从头教 Claude。

40 个 Skills 听起来很多，但其实就是 40 个"我平时就是这么干的"，只不过现在 Claude 也学会了。

如果你还没开始用 Skills，建议从最简单的开始，给自己最常重复的一个操作写一个 Skill，哪怕只有 10 行。跑起来之后你就会停不下来...

本文参考：Thariq Shehata（Anthropic 工程师）的推文 |

附：原文完整翻译

《Lessons from Building Claude Code: How We Use Skills》

Skills 已经成为 Claude Code 中使用最广泛的扩展点之一。它灵活、易于制作、分发也很简单。

但正因为太灵活，反而让人不知道怎么用才最好。什么类型的 Skills 值得做？写好一个 Skill 的秘诀是什么？什么时候该把它分享给别人？

我们在 Anthropic 内部大量使用 Claude Code 的 Skills，目前已有数百个在日常运转。以下是我们总结出的经验：如何用 Skills 加速开发。

如果你刚接触 Skills，建议先阅读相关文档或观看我们最新的课程，本文假设你已经对 Skills 有一定了解。

有一个常见的误解：Skills "不就是 markdown 文件嘛"。但 Skills 最有意思的地方恰恰在于，它不只是文本文件。它是一个文件夹，可以包含脚本、资源、数据等等，智能体能自动发现、探索和使用这些内容。

在 Claude Code 中，Skills 还支持配置选项，包括注册动态 Hooks（自动触发的检查钩子）。

我们发现，最有意思的 Skills 往往是那些巧妙利用了配置选项和文件夹结构的。

梳理完我们所有的 Skills 后，我们发现它们大致归为几个反复出现的类别。好的 Skills 干净利落地落在某一类里；让人困惑的那些，往往横跨好几类。这不是一份终极清单，但可以帮你检查：你的团队是不是还缺了哪一类。

1. 库/SDK 知识类

教 Claude 如何正确使用某个库、CLI 工具或 SDK。既可以针对内部库，也可以针对 Claude Code 有时会用错的常见库。通常会包含一个参考代码片段文件夹，以及一份踩坑清单（Gotchas），提醒 Claude 写脚本时需要避开的陷阱。

示例：

• billing-lib：你的内部计费库，边界情况、容易踩的坑等
• internal-platform-cli：内部 CLI 封装工具的每个子命令，附带使用场景说明
• frontend-design：让 Claude 更懂你的设计系统

2. 验证类

描述如何测试或验证代码是否正常工作。通常会搭配 Playwright（自动化测试工具）、tmux（终端复用工具）等外部工具来完成验证。

验证类 Skills 对确保 Claude 输出的正确性极其有用。值得让一个工程师花一整周专门打磨这类 Skills。

可以考虑这样的技巧：让 Claude 录制输出过程的视频，这样你能直接看到它测了什么；或者在每一步强制执行程序化断言来检查状态。这些通常通过在 Skill 中包含各种脚本来实现。

示例：

• signup-flow-driver：在无头浏览器（在后台无界面运行的浏览器）中跑完注册 → 邮箱验证 → 引导流程，每一步都有状态断言的钩子
• checkout-verifier：用 Stripe 测试卡驱动结账界面，验证发票是否真的落在了正确的状态
• tmux-cli-driver：用于需要终端交互界面的交互式 CLI 测试

3. 数据与监控类

连接你的数据和监控系统。可能包含带凭证的数据获取库、特定的仪表盘 ID 等，以及常用工作流或数据获取方式的说明。

示例：

• funnel-query："要看注册 → 激活 → 付费的漏斗，该 join 哪些事件？" 加上真正存放规范 user_id 的那张表
• cohort-compare：对比两个用户群的留存或转化，标记统计显著性差异，链接到分群定义
• grafana：数据源 UID、集群名称、问题 → 仪表盘查找表

4. 工作流自动化类

把重复性的工作流程自动化成一个命令。指令本身通常很简单，但可能依赖其他 Skills 或 MCP 服务。把之前的运行结果保存在日志文件里，能帮助模型保持一致性，并反思之前的执行情况。

示例：

• standup-post：汇总任务跟踪器、GitHub 活动和之前的 Slack 消息 → 格式化的站会报告，只展示变化部分
• create--ticket：强制执行字段规范（合法的枚举值、必填字段），加上创建后的工作流（通知审阅者、在 Slack 贴链接）
• weekly-recap：合并的代码提交 + 已关闭的工单 + 部署记录 → 格式化周报

5. 脚手架类

为代码库中的特定功能生成框架样板代码。可以和可组合的脚本结合使用。当脚手架包含自然语言描述的需求、不能纯靠代码覆盖时，尤其好用。

示例：

• new--workflow：用你的注解搭建一个新的服务/工作流/处理器
• new-migration：数据库迁移文件模板，加上常见踩坑清单
• create-app：预装好认证、日志和部署配置的新内部应用

6. 代码审查类

在团队内强制执行代码质量标准，辅助代码审查。可以包含确定性的脚本或工具来保证稳健性。你可能想把它们作为 Hooks 的一部分自动运行，或放在 GitHub Action 里执行。

• adversarial-review：启动一个"全新视角"的子智能体来挑刺，修复问题，反复迭代，直到发现的问题降级为吹毛求疵
• code-style：强制执行代码风格，尤其是 Claude 默认做得不好的那些
• testing-practices：怎么写测试、该测什么的指导

7. 部署类

帮你在代码库中拉取、推送和部署代码。可能会引用其他 Skills 来收集数据。

示例：

• babysit-pr：监控一个代码提交 → 重试不稳定的自动化测试 → 解决合并冲突 → 启用自动合并
• deploy-：构建 → 冒烟测试（快速验证基本功能）→ 渐进式流量切换并对比错误率 → 出现回退时自动回滚
• cherry-pick-prod：隔离工作区 → cherry-pick → 解决冲突 → 按模板提交代码

8. 调试与排查类

从一个症状出发（一个 Slack 讨论串、一条告警或一个错误签名），通过多工具联合调查，最终生成一份结构化报告。

示例：

• -debugging：为流量最大的服务梳理"症状 → 工具 → 查询模式"的映射关系
• oncall-runner：拉取告警 → 排查常见嫌疑 → 格式化输出调查结果
• log-correlator：给定一个请求 ID，从所有可能经手的系统中拉取匹配日志

9. 运维与维护类

执行日常维护和运维操作，其中一些涉及破坏性操作，需要护栏保护。让工程师在关键操作中更容易遵循最佳实践。

示例：

• -orphans：发现孤立的 Pod/卷 → 发到 Slack → 观察期 → 用户确认 → 级联清理
• dependency-management：你团队的依赖审批工作流
• cost-investigation："为什么存储/出口流量费突然飙升"，附带具体的存储桶和查询模式

确定了要做什么 Skill 之后，怎么把它写好？以下是我们总结的最佳实践和窍门。

聚焦 Claude 不知道的东西

Claude Code 对你的代码库了解很多，Claude 本身对编程也很在行，包括很多默认的做法偏好。如果你发布的 Skill 主要是知识类的，试着聚焦在那些能把 Claude 从惯性思维中拉出来的信息上。

前端设计 Skill 就是一个好例子，由 Anthropic 的一位工程师在与客户反复迭代中打造，目标是提升 Claude 的设计品味，避开那些经典的"坏习惯"，比如千篇一律的 Inter 字体和紫色渐变。

踩坑清单是最高价值内容

任何 Skill 中信息密度最高的部分就是踩坑清单（Gotchas）。这些内容应该从 Claude 使用你的 Skill 时常见的失败点中积累。理想情况下，你会持续更新 Skill 来捕获这些经验。

用文件系统做渐进式信息披露

正如前面说的，Skill 是一个文件夹，不只是一个 markdown 文件。换个角度想：整个文件系统就是你做上下文工程（context engineering）和渐进式信息披露（按需逐层展示信息，避免一次性过载）的阵地。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时机去读取。

最简单的做法是指向其他 markdown 文件让 Claude 按需阅读。比如，你可以把详细的函数签名和用法示例拆分到 references/api.md 中。

另一个例子：如果最终输出是一个 markdown 文件，你可以在 assets/ 目录下放一个模板文件让 Claude 复制使用。

你可以建参考资料、脚本、示例等文件夹，帮助 Claude 更高效地工作。

给 Claude 灵活度

Claude 通常会严格遵循你的指令，而 Skills 复用性很高，所以要注意别在指令中写得太具体。给 Claude 它需要的信息，但也给它适应具体情况的灵活空间。

用 config.json 做首次配置

有些 Skills 需要用户提供上下文信息才能运行。比如，一个发站会报告到 Slack 的 Skill，可能需要 Claude 先问用户发到哪个频道。

好的做法是把这些配置信息存在 Skill 目录下的 config.json 文件里。如果配置还没设好，智能体就会主动向用户询问。

把描述当触发器来写

Claude Code 启动会话时，会构建一份所有可用 Skills 的清单及其描述。Claude 扫描这份清单来判断"这个请求有没有对应的 Skill？"。也就是说，描述字段不是摘要，而是触发条件，告诉 Claude 什么时候该调用这个 Skill。

给 Skill 加上记忆

有些 Skills 可以通过存储数据来实现一种"记忆"。存储方式随你选：简单的可以是只追加的文本日志或 JSON 文件，复杂的可以用 SQLite（轻量级数据库）。

比如，一个 standup-post Skill 可以维护一份 standups.log，记录它发过的每一条站会报告。下次运行时，Claude 读取自己的历史，就能判断从昨天到现在发生了什么变化。

存在 Skill 目录下的数据在升级时可能会被删除，所以应该存在稳定目录里。目前我们提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定存储路径。

给 Claude 配上代码工具箱

你能给 Claude 最强大的工具之一就是代码。给它脚本和库，让它把精力花在组合编排上：决定下一步做什么，而不是从零重写样板代码。

比如，在数据分析 Skill 中，你可以放一组从事件源获取数据的辅助函数。Claude 就能即时生成脚本，组合这些功能来做更高级的分析，回答类似"周二发生了什么？"这样的问题。

用会话级 Hooks 做按需护栏

Skills 可以包含只在被调用时才激活的 Hooks，在整个会话期间持续生效。适合那些平时不需要、但特定场景下极其有用的强约束型钩子。

例如：

• /careful：通过 PreToolUse（工具调用前拦截钩子）匹配命令，拦截 rm -rf、DROP TABLE、force-push、kubectl delete。只有你确定要操作生产环境时才开，全天候挂着会让人抓狂
• /freeze：拦截所有不在指定目录内的编辑操作。调试时很好用："我想加日志，但不想不小心'修复'了不相关的代码"

分发与共享

Skills 最大的好处之一就是可以和团队共享。

分享 Skills 有两种方式：

• 把 Skills 提交到代码仓库（放在 ./.claude/skills 目录下）
• 制作成插件，通过 Claude Code 插件市场上传和安装

对于在少量仓库间协作的小团队，直接提交到仓库里效果很好。但每个提交进去的 Skill 都会占用模型的一点上下文空间。随着规模扩大，内部插件市场能让你分发 Skills，同时让团队成员自行决定安装哪些。

哪些 Skills 该上市场？怎么提交？

我们没有一个中央团队来拍板；我们的做法是让最有用的 Skills 自然涌现出来。如果你有一个想让大家试试的 Skill，可以上传到 GitHub 的沙盒文件夹，然后在 Slack 或其他渠道推荐。

一旦某个 Skill 获得了足够的关注（由作者自行判断），就可以提交代码把它移入市场。

需要提醒的是，创建质量不高或重复的 Skills 很容易，所以发布前确保有某种审核机制很重要。

跨 Skill 依赖

你可能会有互相依赖的 Skills。比如，一个文件上传 Skill 负责上传，另一个 CSV 生成 Skill 负责生成 CSV 再上传。这种依赖管理目前还没有原生支持，但你可以直接按名称引用其他 Skills，模型会自动调用已安装的。

追踪 Skill 使用情况

为了了解每个 Skill 的表现，我们用了一个 PreToolUse Hook 来记录公司内部的使用情况。这样就能发现哪些 Skills 很受欢迎，哪些触发率低于预期。

结语

Skills 是极其强大、极其灵活的智能体工具，但一切仍处于早期，我们都在摸索怎么用才最好。

与其说这是一份权威指南，不如把它当作我们实践中验证过的一份实用技巧合集。理解 Skills 最好的方式就是动手试，看看什么对你有效。我们的大多数 Skills 一开始也就几行文字加一条踩坑记录，后来因为大家不断把 Claude 碰到的新边界情况补进去，才越来越好。

希望这篇文章对你有帮助，有任何问题欢迎随时提问。