摘要：Anthropic 工程师 Thariq 复盘 Claude Code 团队使用 Skills 的经验：九类常见场景、写好 skill 的实践技巧，以及如何在团队间分发。
本文翻译自 Lessons from Building Claude Code: How We Use Skills
作者：@trq212
发布时间：2026-03-17
翻译：searchpcc
授权：未获明确授权，仅作学习交流，如有异议请联系删除
Skills 已经成了 Claude Code 里最常用的扩展点之一。它们灵活、易于创建、也容易分发。
但也正因为它太灵活，反而让人很难搞清楚到底怎么用才最好。哪些 skill 值得做？写一个好 skill 的秘诀是什么？什么时候应该把它分享给别人？
我们在 Anthropic 内部已经大量使用 skills，目前有数百个处于活跃使用状态。下面这些，是我们在用 skills 加速自己开发过程中总结出来的经验。
什么是 Skills？
如果你是第一次接触 skills，建议先读官方文档 或者看我们最新在 Skilljar 上的 Agent Skills 课程 ，这篇文章默认你已经对 skills 有基本了解。
一个常见的误解是 skills 就是"一些 markdown 文件而已"——但 skills 最有意思的地方恰恰在于，它不是单纯的文本文件，而是一个文件夹，可以包含脚本、资源、数据等等，agent 可以去发现、探索、操作这些内容。
在 Claude Code 里，skills 还有丰富的配置选项 ，包括注册动态 hooks。
我们发现，Claude Code 里最出彩的那些 skills，往往都是把这些配置项和文件夹结构用出了花样。
Skills 的分类
在梳理了我们所有的 skills 之后，我们发现它们会自然而然地聚成几个固定的类别。好 skill 通常可以干净地归到某一类；让人困惑的 skill 则常常横跨几类。下面这份分类不是定论，但可以用来对照一下，看看你们组织里是不是还有哪种类型的 skill 没覆盖。
1. 库与 API 参考（Library & API Reference）
用来告诉 Claude 如何正确使用某个库、CLI 或 SDK 的 skills。既可以是内部库，也可以是 Claude Code 经常用不好的公共库。这类 skill 通常会附带一个参考代码片段的文件夹，以及一份 Claude 写脚本时容易踩的坑清单。
例子：
- billing-lib — 你家的内部计费库：边界情况、陷阱，等等
- internal-platform-cli — 你家内部 CLI 封装的每个子命令，配上什么时候该用的说明
- frontend-design — 让 Claude 更好地遵循你家的设计系统
2. 产品验证（Product Verification）
这类 skill 描述如何测试或验证你的代码确实在工作。通常会搭配 playwright、tmux 等外部工具一起做验证。
验证类 skill 对于保证 Claude 的产出正确极其有用。花一个工程师一周时间把验证类 skill 做到极致，都是值得的。
可以考虑一些具体手段，比如让 Claude 把它测试过程录成视频，让你能看到它到底验证了什么；或者在每一步对状态做程序化断言。这些通常通过在 skill 里打包一堆脚本来实现。
例子：
- signup-flow-driver — 在无头浏览器里跑通"注册 → 邮件验证 → 新手引导"，并在每一步留出断言状态的 hook
- checkout-verifier — 用 Stripe 测试卡驱动结账 UI，验证发票确实落到了正确状态
- tmux-cli-driver — 用于需要 TTY 的交互式 CLI 测试
3. 数据拉取与分析（Data Fetching & Analysis）
连接你家数据和监控栈的 skills。可能包括带凭证拉数据的库、具体的 dashboard id 等等，也会附上常见工作流和拿数据的方法。
例子：
- funnel-query — “要看’注册 → 激活 → 付费’的漏斗，需要 JOIN 哪些事件？” 外加那张真正保存着正统 user_id 的表
- cohort-compare — 对比两个 cohort 的留存或转化，标出有统计显著性的差异，并链到人群定义
- grafana — datasource UID、集群名、以及"问题 → dashboard"的对照表
4. 业务流程与团队自动化（Business Process & Team Automation）
把重复性的工作流浓缩成一条命令的 skills。这类 skill 本身的指令通常相对简单，但可能对其他 skill 或 MCP 有比较复杂的依赖。对这类 skill，把历次执行结果记在 log 里，对模型保持一致性以及反思过往执行很有帮助。
例子：
- standup-post — 聚合你的 ticket 系统、GitHub 活动和之前的 Slack 内容，生成结构化 standup（只给增量）
- create-<ticket-system>-ticket — 强制 schema（合法枚举值、必填字段），再加上创建后的流程（@上 reviewer、在 Slack 里贴链接）
- weekly-recap — 合并过的 PR + 关闭的 ticket + 发布记录 → 排版好的周报
5. 代码脚手架与模板（Code Scaffolding & Templates）
针对代码库里某一类功能生成框架骨架的 skills。你可以把这些 skill 和可组合的脚本搭配起来。当你的脚手架里有那种无法纯用代码表达的自然语言要求时，这类 skill 尤其好用。
例子：
- new-<framework>-workflow — 按你的约定脚手架出一个新的 service / workflow / handler
- new-migration — 你家的 migration 模板，附上常见的坑
- create-app — 新建一个内部应用，预先接好认证、日志和部署配置
6. 代码质量与评审（Code Quality & Review）
在组织内部强制代码质量、协助 code review 的 skills。可以包含确定性脚本或工具以保证健壮性。你可能会想通过 hooks 自动触发它们，或者放到 GitHub Action 里跑。
- adversarial-review — 起一个"新鲜视角"的 subagent 来挑刺、落地修复、反复迭代直到只剩一些鸡毛蒜皮
- code-style — 强制代码风格，尤其是那些 Claude 默认情况下做不好的风格
- testing-practices — 说明如何写测试、测什么
7. CI/CD 与部署（CI/CD & Deployment）
帮你在代码库里拉代码、推代码、部署代码的 skills。这类 skill 可能会引用其他 skill 去收集数据。
例子：
- babysit-pr — 盯着一个 PR：重试 flaky CI、解决合并冲突、打开 auto-merge
- deploy-<service> — 构建 → 冒烟测试 → 灰度放量（对比错误率）→ 发现回归自动回滚
- cherry-pick-prod — 独立 worktree → cherry-pick → 解决冲突 → 按模板开 PR
8. 运维手册（Runbooks）
从一个症状出发（比如 Slack 里的线索、一个告警、或者一段错误签名），走一遍多工具排查流程，最后产出一份结构化的报告。
例子：
- <service>-debugging — 把"症状 → 工具 → 查询模式"的对照表建好，针对你家流量最大的服务
- oncall-runner — 拉告警 → 检查惯犯 → 格式化结论
- log-correlator — 给一个 request id，从所有可能经手过它的系统拉出对应的日志
9. 基础设施运维（Infrastructure Operations）
执行常规维护和运维流程的 skills——有些会涉及破坏性操作，用 skill 加一层护栏反而更合适。这类 skill 能让工程师在关键操作中更容易遵循最佳实践。
例子：
- <resource>-orphans — 找出孤儿 pod/volume → 发 Slack → 留缓冲期 → 用户确认 → 级联清理
- dependency-management — 你家组织的依赖审批流程
- cost-investigation — “为什么这个月我们的存储/出站费用突然涨了？” 附上具体的 bucket 和查询模式
写 Skill 的技巧
决定做哪类 skill 之后，具体怎么写呢？下面是我们总结出的一些最佳实践和小技巧。
我们最近还发布了 Skill Creator ，让在 Claude Code 里创建 skill 更容易。
别说那些显而易见的事
Claude Code 对你的代码库知道不少，Claude 本身也懂不少编程知识，带着很多默认偏好。如果你写的是一个以"知识"为主的 skill，应该聚焦在那些能把 Claude 从它惯常思路里拽出来的信息。
frontend design skill 就是个好例子——Anthropic 的一位工程师通过和客户反复迭代"怎么让 Claude 的设计品味变好"做出来的，专门避开了 Inter 字体、紫色渐变这些俗套。
建一个 Gotchas（坑点）章节
任何 skill 里含信息量最大的部分，都是 Gotchas 章节。它应该由 Claude 使用 skill 时反复踩到的常见失败点攒起来。理想情况下，你会随着时间推移不断更新这份清单，把新遇到的坑也沉淀进去。
用好文件系统和渐进式披露
再说一次：skill 是一个文件夹，不只是一个 markdown 文件。你应该把整个文件系统当成上下文工程和渐进式披露的一种形式——告诉 Claude 你 skill 里有哪些文件，它会在合适的时机去读。
最简单的渐进式披露，就是指向其他 markdown 文件让 Claude 按需读取。比如，你可以把详细的函数签名和使用示例拆到 references/api.md 里。
再举一例：如果你最终要输出的是一份 markdown 文件，你可以把模板文件放到 assets/ 里，让 Claude 复制过去用。
你可以有若干文件夹存参考资料、脚本、示例等等，帮助 Claude 更高效地工作。
别把 Claude 绑死
Claude 一般会尽量遵循你给的指令，而 skill 又是会被反复复用的，所以你要小心别在指令里写得太具体。给 Claude 它需要的信息，但留足够的余地让它根据情况适应。比如：
想清楚初始化
有些 skill 可能需要从用户那里拿一些初始上下文。比如，你做一个往 Slack 贴 standup 的 skill，你可能希望 Claude 先问"要贴到哪个频道"。
一个好用的模式是把这种设置信息存到 skill 目录下的 config.json 里（参考上图）。如果 config 还没配置，agent 就主动问用户。
如果你希望 agent 提结构化的多选问题，可以在指令里让 Claude 用 AskUserQuestion 这个工具。
Description 字段是写给模型看的
Claude Code 启动一个会话时，会把每个可用 skill 的 description 汇总成一份清单。Claude 扫这份清单来判断"这次请求有没有对应的 skill"。也就是说，description 字段不是给人看的摘要——而是在描述"什么时候该触发这个 skill"。
记忆与存储数据
有些 skill 可以通过在自身里存数据，实现某种形式的记忆。可以简单到一个 append-only 的 text log 或 JSON 文件，也可以复杂到一个 SQLite 数据库。
比如一个 standup-post skill，可以维护一个 standups.log，记下每次产出的 standup；下次运行时，Claude 读自己的历史，就能分辨"从昨天到今天哪些变了"。
存在 skill 目录里的数据在 skill 升级时可能会被删掉，所以你应该把它存到一个稳定的位置——目前我们提供 ${CLAUDE_PLUGIN_DATA} 作为每个 plugin 的稳定数据目录。
把脚本存起来，让它生成代码
你能给 Claude 的最强工具之一，就是代码本身。给 Claude 脚本和库，它就可以把每一轮的精力花在组合上——决定"下一步做什么"，而不是一遍遍重写样板代码。
举个例子，你的数据科学 skill 里可以放一个函数库，用来从事件源拉数据。为了让 Claude 能做更复杂的分析，你可以像下面这样给它一堆 helper 函数：
这样 Claude 就能临场写脚本，把这些函数组合起来做更高级的分析，比如你问它：“周二到底发生了什么？”
按需 hooks（On Demand Hooks）
Skill 可以包含只在它被调用时才激活、并在当前会话里一直生效的 hooks。适合那些你不想一直开着、但某些场景下又很有用的、更"偏执"一些的 hooks。
比如：
- /careful — 通过 PreToolUse matcher 拦截 Bash 里的 rm -rf、DROP TABLE、force-push、kubectl delete。只有你明确知道自己在碰生产时才想开；如果一直开着会把人折磨疯
- /freeze — 拦截所有不在指定目录下的 Edit/Write。调试时很有用：“我想加日志，但老是不小心去’修’不相关的东西”
分发 Skills
Skills 的一大优势，是你可以把它分享给团队里的其他人。
分享 skill 一般有两种方式：
- 把你的 skills check 进 repo（放
./.claude/skills下） - 做一个 plugin，再搭一个 Claude Code Plugin marketplace，让用户上传和安装 plugin（更多内容见文档 ）
对跨几个 repo 的小团队来说，直接把 skill 签入 repo 就挺好用。但每个被签入的 skill 都会给模型的上下文添一点负担。当你规模变大，内部 plugin marketplace 能让你分发 skill，并让团队自己决定安装哪些。
管理一个 marketplace
怎么决定哪些 skill 进 marketplace？谁来提交？
我们没有一个集中团队去拍板；我们是有机地去发现那些最有用的 skill。如果你有一个想让大家试用的 skill，可以先把它上传到 GitHub 的 sandbox 目录下，然后在 Slack 或其他场合把链接发出来。
当一个 skill 有了足够的影响力（由 skill 的 owner 自己判断），他们可以提 PR 把它合进正式的 marketplace。
一句警告：造出糟糕的或者重复的 skill 其实挺容易，所以在上线之前有一层 curation 机制很重要。
组合 skill
你可能会想有一些互相依赖的 skill。比如，你有一个文件上传 skill、还有一个 CSV 生成 skill——后者做出一个 CSV 然后上传。这种依赖管理目前还没在 marketplace 或 skill 里原生支持，但你可以直接在一个 skill 里按名字引用另一个，只要另一个已经安装，模型就会去调用它。
度量 skill
为了了解一个 skill 的表现，我们在公司内部用一个 PreToolUse hook 记录 skill 的使用情况（示例代码在这 ）。这样我们就能识别出哪些 skill 很受欢迎、哪些相对于我们的预期触发得不够。
结语
Skills 是非常强大、非常灵活的 agent 工具，但现在还处于早期，大家都还在摸索怎么把它用到最好。
把这篇文章当成一个有用技巧的集合就好——而不是某种权威指南。理解 skill 最好的方式就是动手开干、尝试、看看什么对你有效。我们大多数 skill 一开始都只有几行字和一个小坑点，后来因为大家不停往里面加新遇到的边界情况，才慢慢变得好用。
希望这篇对你有帮助，有问题随时告诉我。
