要点速览
- Skills 已经成为 Claude Code 最常用、最灵活的扩展机制之一，本质上是可包含脚本、资源和数据的文件夹，而不只是 Markdown 文件。
- Anthropic 内部的 Skills 大致会落入 API 参考、验证、数据分析、团队自动化、脚手架、代码质量、部署、Runbook 和基础设施运维等几类。
- 高质量 Skill 的关键在于写出真正高信号的 gotchas、利用文件系统做渐进式披露 (progressive disclosure)，并避免把 Claude 限制得过死。
- Skill 的 description 字段主要是写给模型看的，决定模型何时触发它；脚本、钩子 (hooks) 和持久化数据则能显著提升 Skill 的能力边界。
- 随着团队规模增长，Skill 市场和使用监控会变得越来越重要，但最好的 Skill 往往仍然来自小步迭代和真实问题沉淀。
原文链接 原文：English Original 作者：Thariq (@trq212)，Anthropic Claude Code 开发者
Skills 已经成为 Claude Code 中使用最频繁的扩展点之一。它灵活、容易制作，也便于分发。
但这种灵活性也让人更难判断什么方式才是最佳实践。什么类型的 Skill 值得做？写好一个 Skill 的诀窍是什么？又该在什么时机分享给别人？
在 Anthropic，我们已经在 Claude Code 中大量使用 Skills，目前有数百个 Skill 正在活跃使用中。下面这些，就是我们在用 Skills 加速开发过程中总结出的经验。
如果你刚接触 Skills，我建议先读一下我们的文档，或者看看我们在新 Skilljar 上发布的 Agent Skills 最新课程。本文默认你已经对 Skills 有一定了解。
我们经常听到一个常见误解：有人觉得 Skill “就是 Markdown 文件”。但 Skill 最有意思的地方恰恰在于，它不只是文本文件，而是一个文件夹。这个文件夹里可以包含脚本、资源、数据等内容，代理 (agent) 可以发现、探索并操作这些内容。
在 Claude Code 中，Skill 还支持丰富的配置选项，包括注册动态钩子 (dynamic hooks)。
我们发现，Claude Code 里最有意思的一些 Skill，往往都是把这些配置选项和文件夹结构用得很巧妙的。
在梳理完我们所有的 Skill 之后，我们发现它们大致会聚类到几个反复出现的类别中。最好的 Skill 通常会清晰地落在某一个类别里；那些让人困惑的 Skill，往往是横跨了好几类。这并不是一份权威清单，但它很适合帮助你思考：你的组织内部是不是还缺了某几类 Skill。
这类 Skill 用来解释如何正确使用某个库、CLI 或 SDK。它们既可以服务于内部库，也可以用于那些 Claude Code 有时不太擅长处理的通用库。这类 Skill 通常会附带一个参考代码片段目录，以及一份 Claude 在写脚本时需要避开的坑点清单。
示例：
这类 Skill 描述如何测试或验证你的代码是否正常工作。它们通常会和 playwright、tmux 等外部工具配合使用来完成验证。
验证类 Skill 对于确保 Claude 产出的正确性极其有用。甚至值得让一位工程师专门花一周时间，把你的验证 Skill 打磨到非常出色。
你可以考虑一些技巧，比如让 Claude 录制它产出结果的视频，这样你就能准确看到它测试了什么；或者在每一步都强制加入基于程序的状态断言。这类能力通常是通过在 Skill 中包含各类脚本来实现的。
示例：
这类 Skill 会接入你的数据和监控体系。它们可能会包含带凭证的数据抓取库、特定 dashboard 的 ID 等，也会包含常见工作流或数据获取方式的说明。
示例：
这类 Skill 会把重复性工作流自动化成一条命令。它们通常是相对简单的指令集合，但可能会依赖其他 Skill 或 MCP。对于这类 Skill，把之前的执行结果保存在日志文件里，可以帮助模型保持一致性，并回顾工作流过去的执行情况。
示例：
这类 Skill 用于为代码库中特定功能生成框架级脚手架。你可以把它们和可组合脚本结合使用。尤其当你的脚手架还包含一些无法完全靠代码表达的自然语言要求时，这类 Skill 会特别有价值。
示例：
这类 Skill 用于在组织内部统一代码质量标准，并辅助做代码评审。为了获得最高鲁棒性，它们可以结合确定性脚本或工具。你也可以把这些 Skill 自动接入钩子，或者放进 GitHub Action 里运行。
这类 Skill 帮助你在代码库里拉取、推送和部署代码。它们也可能引用其他 Skill 来补齐所需信息。
示例：
这类 Skill 接收某个症状输入，例如一条 Slack 线程、一个告警或某种错误特征，然后串联多个工具完成排查，并输出结构化报告。
示例：
这类 Skill 用于执行日常维护和运维流程，其中有些还涉及破坏性操作，因此很适合加上护栏。它们能让工程师在关键操作中更容易遵循最佳实践。
示例：
当你决定要做一个 Skill 后，该怎么写？下面是我们总结出的一些最佳实践、技巧和经验。
我们最近还发布了 Skill Creator，让在 Claude Code 中创建 Skill 变得更容易。
Claude Code 对你的代码库已经知道很多，Claude 对编程本身也知道很多，而且自带不少默认偏好。如果你发布的是一个以知识为主的 Skill，那就应该尽量聚焦那些能把 Claude 从默认思路中“推出来”的信息。
frontend design 这个 Skill 就是个很好的例子。它由 Anthropic 的一位工程师打造，通过和客户反复迭代来提升 Claude 的设计品味，比如避免 Inter 字体和紫色渐变这种经典套路。
任何 Skill 中信号密度最高的内容，往往都是 Gotchas 部分。这个部分应该围绕 Claude 在使用你的 Skill 时最常犯的错误不断积累。理想情况下，你应该随着时间持续更新 Skill，把这些 gotcha 不断补进去。
就像前面说的，Skill 是一个文件夹，不只是一个 Markdown 文件。你应该把整个文件系统都视为一种上下文工程 (context engineering) 和渐进式披露 (progressive disclosure) 手段。告诉 Claude 你的 Skill 目录里有哪些文件，它就会在合适的时候读取它们。
最简单的渐进式披露方式，就是把 Claude 指向其他 Markdown 文件。例如，你可以把详细函数签名和使用示例拆分到 references/api.md 中。
再比如，如果你的最终输出是一个 Markdown 文件，那你可以在 assets/ 里放一个模板文件，供 Claude 复制使用。
你还可以准备 references、scripts、examples 等目录，帮助 Claude 更高效地工作。
Claude 通常会尽量遵循你的指令，而因为 Skill 是高度可复用的，你需要特别小心，不要把说明写得过于具体。你要给 Claude 足够的信息，但也要给它足够的灵活性，让它根据场景调整。
有些 Skill 需要先从用户那里拿到上下文后才能设置好。例如，如果你在做一个把 standup 发到 Slack 的 Skill，你可能会希望 Claude 先问清楚要发到哪个 Slack 频道。
一种不错的模式，是把这类初始化信息存进 Skill 目录下的 config.json 文件，就像上面的例子那样。如果配置还没准备好，代理就可以向用户发问。
如果你希望代理用结构化的多选题形式向用户提问，也可以指示 Claude 使用 AskUserQuestion 工具。
当 Claude Code 启动一个会话时，它会为所有可用 Skill 建立一个包含描述的列表。Claude 会扫描这个列表来判断“这个请求有没有对应的 Skill”。所以 description 字段并不是摘要，它本质上是在描述“这个 PR 什么时候应该触发”。
有些 Skill 可以通过在目录里存储数据来具备某种“记忆”。你可以把数据存在最简单的追加式文本日志或 JSON 文件里，也可以复杂到使用 SQLite 数据库。
例如，一个 standup-post Skill 可以保留一份 standups.log，记录它写过的每一篇 standup。这样下一次运行时，Claude 就能读取自己的历史，知道和昨天相比发生了什么变化。
不过，存放在 Skill 目录里的数据在你升级 Skill 时可能会被删除，所以你应该把这类数据放到稳定目录里。截至目前，我们提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定存储目录。
你能给 Claude 的最强大工具之一，就是代码本身。把脚本和库交给 Claude，能让它把交互轮次花在“组合这些能力、决定下一步做什么”上，而不是反复重建样板代码。
例如，在你的数据科学 Skill 中，你可以提供一组从事件源抓取数据的函数库。这样当 Claude 需要做复杂分析时，就能直接调用这些辅助函数。
随后，Claude 可以在运行时按需生成脚本，把这些功能组合起来，以便回答像“周二发生了什么？”这类更复杂的问题。
Skill 可以包含只有在 Skill 被调用时才会激活，并在整个会话期间持续生效的 hooks。对于那些非常有用、但你又不希望它们始终运行的强约束 hook，这种方式尤其合适。
例如：
Skills 最大的好处之一，就是你可以把它们分享给团队里的其他人。
通常有两种分享方式：
对于跨仓库数量不多的小团队来说，把 Skill 直接检入仓库通常就很好用。但每多检入一个 Skill，也会给模型上下文增加一点负担。随着规模扩大，内部插件市场可以帮助你分发 Skill，并让团队成员自行决定安装哪些。
该如何决定哪些 Skill 应该进入 marketplace？大家又该如何提交？
我们没有一个中心化团队来做裁决；相反，我们倾向于让最有用的 Skill 自然浮现出来。如果你有一个希望别人试用的 Skill，你可以先把它上传到 GitHub 的一个 sandbox 文件夹里，再在 Slack 或其他论坛里发给大家。
一旦某个 Skill 已经获得一定 traction，Skill 的拥有者就可以提交一个 PR，把它移动到 marketplace 中。
不过要提醒一点：做出糟糕或重复的 Skill 其实非常容易，所以在正式发布前，最好还是有某种筛选机制来做把关。
你可能会希望让 Skill 之间彼此依赖。例如，你可以有一个文件上传 Skill 负责上传文件，再有一个 CSV 生成 Skill 负责生成 CSV 并上传。这类依赖管理目前还没有在 marketplace 或 Skills 本身里原生支持，但你可以直接通过名称引用其他 Skill，模型在它们已安装的情况下就会调用它们。
为了评估一个 Skill 的表现，我们会使用一个 PreToolUse hook 来记录公司内部的 Skill 使用情况（示例代码见这里）。借助这些日志，我们就能发现哪些 Skill 很受欢迎，或者哪些 Skill 的触发频率比预期更低。
Skills 是代理非常强大且灵活的工具，但这件事仍然处在很早期阶段，大家都还在摸索最佳用法。
与其把这篇文章当成一份权威指南，不如把它看作一组已经被验证有效的经验集合。理解 Skills 的最好办法，还是亲自上手、不断实验、观察什么真正有效。我们的大多数 Skill 一开始都只是几行说明加上一条 gotcha，后来随着 Claude 在更多边界场景里暴露问题，才被大家一点点补充完善。
希望这些内容对你有帮助。如果你有任何问题，欢迎告诉我。