译： https://x.com/trq212/status/2033949937936085378
作者：Anthropic Claude Code 胡子哥 @Thariq
Skills[1] 已经成了 Claude Code 里用得最多的能力扩展方式之一。它们灵活、好做、也便于分发。
但正因为太灵活，大家反而不太确定什么才是最佳实践。到底哪类 Skills 值得做？怎么才能写出一个好的 Skill？什么时候应与他人共享这些技能呢？
我们在 Anthropic 内部大量使用 Claude Code 的 Skills，光是在积极使用的就有好几百个。以下是我们在这个过程中总结出来的经验。
什么是 Skills？
如果你对 Skills 还不太熟悉，建议先去看看我们的文档，或者看看我们最新的 Skilljar 课程：Agent Skills 入门。这篇文章假设你对 Skills 已经有了基本了解。
Skills 不仅仅是 Markdown 文件
一个常见的误解是觉得 Skills"不就是 Markdown 文件嘛"。但 Skills 最有意思的地方恰恰在于：它们不只是文本文件，而是一个文件夹，里面可以包含脚本、素材、数据等等，agent[2] 能自行发现、浏览和操作这些内容。
在 Claude Code 中，Skills 还支持丰富的配置选项，包括注册动态 hooks[3]。
我们发现，最有意思的那些 Skills，往往是巧妙利用了这些配置选项和文件夹结构的。
Skills 的分类
在整理了我们所有的 Skills 之后，我们发现它们大致可以归为以下几类。最好的 Skills 通常只属于其中一类；那些让人摸不着头脑的，往往是横跨了好几类。这不是一个权威的分类方式，但可以帮你检查一下团队里是不是还缺了哪一类。
1. 库与 API 参考类（Library & API Reference）
教模型如何正确使用某个库、CLI[4] 或 SDK[5] 的 Skills。可以是内部库，也可以是那些 Claude Code 偶尔会用错的公共库。这类 Skill 通常会包含一个参考代码片段文件夹，以及一份"Claude 写代码时容易踩的坑"清单。
示例：
- billing-lib — 你们内部的计费库：边界情况、容易出错的地方等
- internal-platform-cli — 内部 CLI 工具的每一个子命令及使用示例
- frontend-design — 让 Claude 更好地适配你们的设计系统[6]
2. 产品验证类（Product Verification）
描述如何测试或验证代码是否正常工作的 Skills，通常会搭配 Playwright[7]、tmux[8] 等外部工具来做验证。
验证类 Skills 对于确保 Claude 的输出正确与否极其重要。花一周时间让一个工程师专门把验证类 Skills 打磨好，绝对物超所值。
可以考虑的技巧：让 Claude 录制它的输出视频，这样你就能看到它到底测了什么；或者在每一步都强制做程序化的状态断言[9]。这些通常是通过在 Skill 里放一系列脚本来实现的。
示例：
- signup-flow-driver — 在无头浏览器[10]中跑完"注册 → 邮件验证 → 新手引导"的全流程，每一步都有状态断言的钩子
- checkout-verifier — 用 Stripe[11] 测试卡驱动结账流程，验证发票最终是否到了正确的状态
- tmux-cli-driver — 用于需要 TTY[12] 的交互式 CLI 测试
3. 数据获取与分析类（Data Fetching & Analysis）
连接你们的数据和监控系统的 Skills。可能会包含带凭证的数据拉取库、特定的 dashboard ID 等，以及关于常见工作流和数据获取方式的说明。
示例：
- funnel-query — "要看’注册 → 激活 → 付费’的漏斗，应该 join 哪些事件？"外加指出那张存有规范 user_id 的表
- cohort-compare — 对比两个用户群的留存或转化，标出统计显著差异，附上分群定义的链接
- grafana — 数据源 UID、集群名称、"问题 → dashboard"对照表
4. 业务流程与团队自动化类（Business Process & Team Automation）
把重复性的工作流自动化为一条命令。这类 Skill 的指令通常比较简单，但可能会依赖其他 Skills 或 MCP[13]。对于这类 Skill，把每次执行的结果保存到日志文件中，有助于模型保持一致性并回顾之前的执行历史。
示例：
- standup-post — 汇总你的工单系统、GitHub 动态和之前的 Slack 消息 → 格式化的站会报告，只展示增量变化
- create-<ticket-system>-ticket — 强制遵循 schema（有效的枚举值、必填字段），加上创建后的流程（通知审核人、在 Slack 里贴链接）
- weekly-recap — 合并的 PR + 关闭的工单 + 部署记录 → 格式化的周报
5. 代码脚手架与模板类（Code Scaffolding & Templates）
为代码库中的某个特定功能生成框架模板代码的 Skills。你可以把这些 Skills 与可组合的脚本搭配使用。当你的模板中有自然语言的要求、纯代码覆盖不了的时候，它们尤其好用。
示例：
- new-<framework>-workflow — 搭建一个新的 service/workflow/handler，带上你们的注解
- new-migration — 数据库迁移文件模板加常见坑点
- create-app — 新建内部应用，预置好认证、日志和部署配置
6. 代码质量与审查类（Code Quality & Review）
在团队内部推行代码质量标准、辅助代码审查的 Skills。可以包含确定性的脚本或工具来保证最大的可靠性。你可能想把这些 Skills 作为 hooks 的一部分自动运行，或者放在 GitHub Action[14] 里。
示例：
- adversarial-review — 启一个全新视角的子 agent 来挑毛病，修复问题，反复迭代直到只剩鸡蛋里挑骨头的小问题
- code-style — 强制执行代码风格，特别是那些 Claude 默认做不好的风格
- testing-practices — 关于怎么写测试、测什么的指南
7. CI/CD 与部署类（CI/CD & Deployment）
帮你拉代码、推代码、部署代码的 Skills。可能会引用其他 Skills 来收集信息。
示例：
- babysit-pr — 监控一个 PR → 重试不稳定的 CI[15] → 解决合并冲突 → 开启自动合并
- deploy-<service> — 构建 → 冒烟测试[16] → 灰度发布并对比错误率 → 出现回归就自动回滚
- cherry-pick-prod — 隔离的 worktree → cherry-pick → 冲突解决 → 用模板创建 PR
8. Runbook 类（Runbooks[17]）
接收一个症状（比如一个 Slack 帖子、一条告警、一个错误签名），走一遍多工具排查流程，最后产出一份结构化的报告。
示例：
- <service>-debugging — 把症状映射到工具和查询模式，覆盖你们流量最大的服务
- oncall-runner — 拉取告警 → 排查常见原因 → 格式化输出排查结论
- log-correlator — 给定一个 request ID，从所有可能碰过这个请求的系统中拉出匹配的日志
9. 基础设施运维类（Infrastructure Operations）
执行日常维护和运维操作的 Skills——其中一些涉及破坏性操作，所以需要防护措施。它们让工程师在做关键操作时更容易遵循最佳实践。
示例：
- <resource>-orphans — 发现孤儿 pod/volume → 发到 Slack → 等待观察期 → 用户确认 → 级联清理
- dependency-management — 你们组织的依赖审批流程
- cost-investigation — “为什么我们的存储/流量账单突然飙了？”——包含具体的 bucket 和查询模式
写好 Skills 的技巧
决定了要做什么 Skill 之后，怎么把它写好？以下是我们发现的一些最佳实践和窍门。
我们最近还发布了 Skill Creator，让在 Claude Code 里创建 Skills 变得更简单。
只写 Claude 不知道的东西
Claude Code 本身就对你的代码库了解很多，而且 Claude 对编程有很多默认判断。如果你要发布一个主要是传递知识的 Skill，请聚焦在那些能让 Claude 跳出常规思维的信息上。
前面提到的 frontend-design Skill 就是一个很好的例子——它是 Anthropic 的一位工程师通过和客户反复迭代打磨出来的，目的是提升 Claude 的设计品味，避免那些经典的"AI 味"，比如 Inter 字体和紫色渐变。
认真写 Gotchas 部分
任何 Skill 中信噪比最高的内容就是 Gotchas[18] 部分。这部分应该从 Claude 使用你的 Skill 时反复踩的坑中积累而来。理想情况下，你会随着时间不断更新 Skill 来捕获这些坑。
把整个文件系统当成渐进式上下文
前面说过，Skill 是一个文件夹，不只是一个 Markdown 文件。你应该把整个文件系统看作一种 context engineering[19] 和渐进式信息披露的手段。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时候去读它们。
最简单的渐进式披露方式就是指向其他 Markdown 文件让 Claude 参考。比如，你可以把详细的函数签名和用法示例拆到 references/api.md 里。
另一个例子：如果你的最终产出是一个 Markdown 文件，你可以在 assets/ 里放一个模板文件供复制使用。
你还可以有专门放参考资料、脚本、示例等的文件夹，帮 Claude 更高效地工作。
给出信息，但留出灵活度
Claude 通常会尽力遵循你的指令，而且因为 Skills 是高度可复用的，你要注意别把指令写得太死。给 Claude 它需要的信息，但也给它根据实际情况灵活调整的空间。
用配置文件做初始化设置
有些 Skills 需要用户提供上下文信息才能运行。比如，你做了一个往 Slack 发站会消息的 Skill，可能需要先问用户发到哪个频道。
一个好的做法是把这些设置信息存到 Skill 目录下的 config.json 文件里。如果配置还没设好，agent 就可以主动问用户。
如果你想让 agent 展示结构化的多选题，可以指示 Claude 使用 AskUserQuestion 工具。
把 Description 当成触发器来写
Claude Code 启动一个会话时，会扫描所有可用 Skills 的列表及其描述。Claude 就是靠这个列表来判断"这个请求有没有对应的 Skill？"这意味着 description 字段不是摘要——它是触发条件。
让 Skill 拥有记忆
有些 Skills 可以通过在自身内部存储数据来实现某种形式的"记忆"。你可以用最简单的追加写入的文本日志或 JSON 文件，也可以用 SQLite 数据库这样复杂的方案。
比如，一个 standup-post Skill 可能会维护一个 standups.log，记录它写过的每一篇站会报告。这样下次运行时，Claude 会读取自己的历史记录，就能知道从上次到现在发生了什么变化。
存在 Skill 目录里的数据在升级 Skill 时可能会被删掉，所以你应该把数据存到一个稳定的位置。目前我们提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定数据目录。
给 Claude 可以直接用的代码
你能给 Claude 的最有力的工具之一就是代码。给 Claude 脚本和函数库，能让它把精力花在组合和决策上，而不是从零开始重写那些模板代码。
比如，你的数据分析 Skill 里可以有一组从事件源拉数据的辅助函数。
Claude 就能在运行时即时生成脚本，把这些函数组合起来做更复杂的分析，比如回答"周二发生了什么？"
善用 Skill 级别的 Hooks
Skills 可以包含只在该 Skill 被调用时才激活的 hooks，持续到会话结束。把那些"平时不想一直开着但有时候特别好用"的强约束 hooks 放在这里。
例如：
- /careful — 通过 PreToolUse 匹配器[20]拦截
rm -rf、DROP TABLE、force-push、kubectl delete等命令。你只在碰生产环境时才需要这个——一直开着会烦死人 - /freeze — 禁止对指定目录以外的文件做任何编辑/写入操作。调试的时候很有用：“我只想加个日志，但总是不小心’修’了无关的代码”
怎么分享 Skills
Skills 最大的好处之一就是可以分享给团队。
你有两种分享方式：
对于人少、仓库也不多的小团队，把 Skills 直接提交到仓库里就够了。但每提交一个 Skill 都会给模型的上下文增加一点负担。随着规模扩大，内部的 plugin 市场能让你更好地分发 Skills，让团队成员自行决定安装哪些。
哪些 Skills 该上市场？怎么提交？
我们没有一个特定团队来拍板；我们尽量让最有用的 Skills 自然涌现出来。如果你有一个想让大家试试的 Skill，可以把它传到 GitHub 的一个沙箱文件夹里，然后在 Slack 或其他论坛里指给大家。
一旦这个 Skill 积累了足够的使用量（由 Skill 的维护者自己判断），他们就可以提一个 PR 把它移到正式的市场里。
需要提醒的是，创建质量差或重复的 Skills 实在太容易了，所以在正式发布前确保有一定的审核机制很重要。
Skill 之间的依赖
你可能会需要 Skills 之间互相依赖。比如，一个文件上传 Skill 负责上传文件，一个 CSV 生成 Skill 生成 CSV 然后调用上传。这种依赖管理目前还没有内置到市场或 Skills 系统中，但你只需要在 Skill 里按名字引用其他 Skill，模型会在该 Skill 已安装的情况下自动调用它。
追踪 Skill 的使用情况
为了了解一个 Skill 用得怎么样，我们使用了一个 PreToolUse hook 来在公司内部记录 Skill 的使用日志（示例代码在这里）。这样我们就能发现哪些 Skills 很受欢迎，哪些的触发率比预期低。
总结
Skills 是非常强大、灵活的 agent 工具，但一切都还处于早期阶段，我们都在摸索最好的使用方式。
这篇文章与其说是一份权威指南，不如说是一个实用技巧合集。理解 Skills 的最好方式就是动手做、大胆试、看看什么管用。我们大多数的 Skills 一开始都只有几行文字加一条 gotcha，是因为大家在 Claude 撞上新的边界情况时不断补充，才越来越好的。
许多些许特别的专有名词标注了释义 因为Skill是设计给普通用户用的辣
Skills：Claude Code 中的一种扩展机制，本质上是一个包含 Markdown 说明文件以及可选的脚本、配置、数据等资源的文件夹。Agent 在执行任务时会读取这些内容来指导自身行为，类似于给 AI 写的"操作手册"。 ↩︎
Agent：智能体，指能够自主执行多步操作（如读写文件、运行命令、调用工具）来完成用户目标的 AI 系统。Claude Code 就是一个 agent。 ↩︎
Hooks：钩子。在 Claude Code 中指在特定时机（如工具调用前后）自动触发的回调机制。可以用来拦截危险操作、记录日志等。 ↩︎
CLI（Command Line Interface）：命令行界面，通过终端输入命令来操作程序的交互方式。 ↩︎
SDK（Software Development Kit）：软件开发工具包，提供一组库和工具，方便开发者集成和使用某项服务或平台的功能。 ↩︎
设计系统（Design System）：一套统一的设计语言和组件库，包含颜色、排版、组件、交互模式等规范，确保产品视觉和体验的一致性。 ↩︎
Playwright：微软开源的浏览器自动化测试框架，支持 Chromium、Firefox、WebKit，常用于端到端（E2E）测试。 ↩︎
tmux（Terminal Multiplexer）：终端复用器，可以在一个终端窗口中创建和管理多个会话，常用于服务器运维和交互式命令行测试。 ↩︎
断言（Assertion）：在测试中用来验证程序实际行为是否符合预期的检查语句。如果断言失败，说明代码有 bug。 ↩︎
无头浏览器（Headless Browser）：没有图形界面的浏览器实例，在后台运行，常用于自动化测试和网页抓取。 ↩︎
Stripe：一个广泛使用的在线支付处理平台，提供 API 让开发者在应用中集成支付功能。它提供测试模式和测试卡号用于开发调试。 ↩︎
TTY（Teletypewriter）：在现代计算中指终端设备或终端模拟器，代表一种需要交互式输入输出的接口。有些命令行程序需要 TTY 才能正常运行。 ↩︎
MCP（Model Context Protocol）：模型上下文协议，Anthropic 推出的一种开放标准，让 AI 模型能够以标准化的方式连接和使用外部工具、数据源和服务。 ↩︎
GitHub Action：GitHub 提供的 CI/CD 自动化平台，可以在代码提交、PR 创建等事件发生时自动运行工作流（如测试、部署等）。 ↩︎
CI（Continuous Integration）：持续集成，指开发者频繁将代码合入主分支，并通过自动化构建和测试来及早发现问题的实践。 ↩︎
冒烟测试（Smoke Test）：一种快速的基本功能验证测试，用来确认系统的核心功能在部署后是否还能正常工作，不做深入测试。名字来源于硬件测试——通电后如果不冒烟就算通过。 ↩︎
Runbook：运维操作手册。传统意义上是一份标准化的操作流程文档，记录了排查和解决特定问题的步骤。在这里指的是把这些排查流程编码成 Skill，让 agent 自动执行排查、诊断并生成报告。 ↩︎
Gotchas：编程领域的常用说法，指那些容易被忽略的坑、陷阱或反直觉的行为。直译为"坑点"或"注意事项"。 ↩︎
Context Engineering（上下文工程）：指精心设计和组织提供给大语言模型的上下文信息（提示词、参考资料、工具描述等），以最大化模型输出质量的实践。 ↩︎
PreToolUse 匹配器：Claude Code hooks 系统中的一种机制，在 agent 调用某个工具（如执行 Bash 命令）之前触发，可以用来检查、拦截或修改即将执行的操作。 ↩︎
Plugin：插件。在 Claude Code 生态中，plugin 是一种可分发的 Skills 打包格式，用户可以从市场安装，也可以自行上传。与直接提交到仓库相比，plugin 更适合大规模团队的分发场景。 ↩︎
前排支持
太牛了佬