原文地址: https://www.linkedin.com/pulse/lessons-from-building-claude-code-how-we-use-skills-thariq-shihipar-iclmc/

概述

本文整理自 Anthropic 团队在 Claude Code 中大规模使用 技能（Skills） 的实践经验：技能是文件夹而不仅是 Markdown，可附带脚本、资源与配置（含钩子），适合把组织内的「怎么做得对」固化为可复用能力。



全文先按 九类常见技能（库/API 参考、产品验证、数据分析、流程自动化、脚手架、代码评审、CI/CD、运维手册、基础设施运维）说明各自用途与命名示例；再给出 写作要点（避免废话、突出 Gotchas、渐进式披露、别把模型绑死、description 写给触发判断、数据放 ${CLAUDE_PLUGIN_DATA}、用脚本减负、按需钩子等）；最后覆盖 团队分发（仓库内 .claude/skills vs 插件市场）、技能组合、以及用钩子做 使用度量。

若你希望系统性地设计或推广技能，可把本文当作一份可对照的检查清单，而非唯一标准答案。

以下为文章原文

技能（Skills）已成为 Claude Code 中最常用的扩展点之一。它们灵活、易于制作，也便于分发。

但这种灵活性也让人难以判断什么做法最好：什么样的技能值得做？写好技能的秘诀是什么？什么时候该分享给他人？

我们在 Anthropic 内部大量使用 Claude Code 的技能，活跃使用的技能数以百计。以下是我们在用技能加速开发过程中总结的经验。

若你还不熟悉技能，建议先阅读官方文档，或在 Skilljar 上观看我们关于 Agent Skills 的最新课程；本文默认你已具备一定基础。

一个常见误解是：技能「不过是 Markdown 文件」。但技能最有趣的地方恰恰在于：它们不只是文本文件，而是一个文件夹，可以包含脚本、资源、数据等，供智能体发现、浏览和操作。

在 Claude Code 中，技能还有多种配置选项，包括注册动态钩子（hooks）。我们发现，许多最有意思的技能会创造性地使用这些配置和目录结构。

技能的类型

在梳理全部技能后，我们发现它们大致会落在以下几类里。最好的技能通常能干净地归入某一类；让人困惑的技能则往往横跨多类。这不是绝对分类，但有助于思考：组织里是否还缺某一类技能。



1. 库与 API 参考

解释如何正确使用某库、CLI 或 SDK。可面向内部库，也可面向 Claude Code 经常踩坑的常见库。这类技能常包含一文件夹参考代码片段，以及一份「要避免的坑」列表，供 Claude 写脚本时对照。

示例：

• billing-lib — 内部计费库：边界情况、常见雷区等

• internal-platform-cli — 内部 CLI 封装：每个子命令及适用场景示例

• frontend-design — 让 Claude 更贴合你们的设计体系

2. 产品验证

描述如何测试或验证代码是否按预期工作，常与 Playwright、tmux 等外部工具配合做验证。

验证类技能对保证 Claude 输出正确性非常有用；值得让工程师花一周时间把验证技能打磨到极致。

可以考虑：让 Claude 录屏展示它测了什么，或在每一步对状态做程序化断言。这类技能里通常会包含多种脚本。

示例：

• signup-flow-driver — 无头浏览器跑完注册 → 邮件验证 → 引导，每步可断言状态

• checkout-verifier — 用 Stripe 测试卡驱动结账 UI，并验证账单是否进入正确状态

• tmux-cli-driver — 需要 TTY 的交互式 CLI 测试

3. 数据获取与分析

连接你们的数据与监控栈。可包含带凭证拉取数据的库、具体仪表盘 ID 等，以及常见工作流或取数方式说明。

示例：

• funnel-query — 「要看注册 → 激活 → 付费该 join 哪些事件」以及真正承载 canonical user_id 的表

• cohort-compare — 对比两群组的留存或转化，标出统计显著差异，并链接到人群定义

• grafana — 数据源 UID、集群名、问题 → 仪表盘对照表

4. 业务流程与团队自动化

把重复工作流收敛成一条命令。说明往往简单，但可能依赖其他技能或 MCP。对这类技能，把历史结果记在日志里，有助于模型保持一致，并回顾以往执行。

示例：

• standup-post — 汇总工单系统、GitHub 活动与往期 Slack → 格式化 standup，只输出增量

• create--ticket— 约束 schema（合法枚举、必填字段）及创建后流程（@评审人、Slack 里贴链接）

• weekly-recap — 合并 PR、关闭工单、部署记录 → 格式化周报

5. 代码脚手架与模板

为代码库中某一类功能生成框架样板。可与可组合的脚本一起使用；当脚手架需求带自然语言、无法完全用代码覆盖时特别有用。

示例：

• new--workflow— 按你们注解脚手架新服务/工作流/处理器

• new-migration — 迁移文件模板 + 常见坑

• create-app — 新内部应用，预置认证、日志与部署配置

6. 代码质量与评审

在组织内落实代码质量并辅助评审。可包含确定性脚本或工具以提高稳健性。也可考虑在钩子或 GitHub Action 里自动运行。

示例：

• adversarial-review — 启动一个「新鲜视角」子智能体做批判，实现修复，迭代到只剩吹毛求疵

• code-style — 落实代码风格，尤其是 Claude 默认做得不好的部分

• testing-practices — 如何写测试、该测什么

7. CI/CD 与部署

在代码库内拉取、推送与部署。可引用其他技能来汇总信息。

示例：

• babysit-pr — 盯着一个 PR → 重试不稳定 CI → 解决合并冲突 → 开启自动合并

• deploy-— 构建 → 冒烟 → 渐进放量并对比错误率 → 回滚

• cherry-pick-prod — 独立 worktree → cherry-pick → 解决冲突 → 带模板的 PR

8. 运维手册（Runbooks）

从症状（Slack 线程、告警、错误特征）出发，串联多工具排查，输出结构化报告。

示例：

• -debugging— 症状 → 工具 → 查询模式，针对高流量服务

• oncall-runner — 拉取告警 → 检查常见原因 → 格式化结论

• log-correlator — 给定 request ID，从所有可能经过的系统拉齐日志

9. 基础设施运维

执行例行维护与运维流程 — 其中部分涉及破坏性操作，更需要护栏。让工程师在关键操作上更容易遵循最佳实践。

示例：

• -orphans— 找孤立 pod/卷 → 发到 Slack → 浸泡期 → 用户确认 → 级联清理

• dependency-management — 组织内的依赖审批流程

• cost-investigation — 「存储/出站费用为什么飙涨」，具体到桶与查询模式

制作技能的技巧

确定要做哪种技能之后，怎么写？以下是我们总结的一些最佳实践与窍门。 我们也发布了 Skill Creator，便于在 Claude Code 中创建技能。



不要陈述显而易见的事

Claude Code 对你的代码库已有不少了解，Claude 对编程也有大量默认观点。若技能主要是知识型，请尽量提供能把 Claude 拉出惯常思路的信息。

frontend-design 是个好例子：由 Anthropic 工程师与客户迭代，提升 Claude 的设计品味，避免 Inter 字体、紫色渐变等套路。

建立「坑点（Gotchas）」区块



任何技能里信息量最高的往往是 Gotchas 区块。应来自 Claude 使用该技能时的真实失败点，并随时间迭代补充。

善用文件系统与渐进式披露



如前所述，技能是文件夹，不只是单个 Markdown。应把整个文件系统当作上下文工程与渐进披露：告诉 Claude 技能里有哪些文件，它会在合适时机阅读。

最简单的渐进披露：把详细函数签名与用法拆到 references/api.md 等文件。

若最终产出是 Markdown，可在 assets/ 放模板供复制使用。

还可以有 references/、scripts/、examples/ 等，帮助 Claude 更高效工作。

避免把 Claude「绑死在轨道上」



Claude 会尽量遵守你的指令；技能又很通用，指令过细反而有害。给出它需要的信息，但保留根据情况调整的余地。

把「安装/配置」想清楚



有些技能需要用户提供上下文。例如做「把 standup 发到 Slack」的技能，可能要先问发到哪个频道。

一种做法：在技能目录里用 config.json 存这类配置；若未配置，再由智能体询问用户。

若希望结构化、多选题式的交互，可指示 Claude 使用 AskUserQuestion 工具。

description 字段是给模型看的

会话开始时，Claude Code 会列出所有可用技能及其 description。Claude 靠这份列表判断「这个请求该不该用某个技能」。因此 description 不是摘要，而是「何时应触发本技能」的说明。



记忆与数据存储



部分技能可通过在目录内保存数据形成某种「记忆」：可以是追加日志、JSON，也可以是 SQLite。

例如 standup-post 可维护 standups.log，下次运行时读取历史，对比与昨天的差异。

注意：技能目录内的数据在升级技能时可能被清空，应把持久数据放在稳定路径；目前我们提供 ${CLAUDE_PLUGIN_DATA} 作为按插件划分的稳定数据目录。

存放脚本并生成代码

能给 Claude 最有力的工具之一就是代码。提供脚本与库，让 Claude 把回合用在编排与决策上，而不是反复手写样板。



例如数据科学技能里可放一套从事件源取数的函数库；复杂分析时，Claude 可现场生成脚本组合这些能力，响应「周二发生了什么？」这类问题。



按需钩子（On Demand Hooks）

技能可包含仅在调用该技能时激活、并持续到会话结束的钩子。适合那些不想全局常驻、但在某些场景极其有用的强意见钩子。

例如：

• /careful — 通过 Bash 的 PreToolUse 匹配器拦截 rm -rf、DROP TABLE、强推、kubectl delete 等。只在碰生产时需要；一直开着会让人抓狂。

• /freeze — 拦截非特定目录下的 Edit/Write。调试时很有用：「我只想加日志，却总不小心改到无关代码」。

分发技能

技能的一大好处是可以与团队共享。

常见两种方式：

1. 把技能提交进仓库（例如 ./.claude/skills）

1. 做成插件，通过 Claude Code 插件市场让用户上传与安装（详见文档）

仓库少、团队小的时候，把技能放进仓库通常够用。但每个检入的技能都会增加一点模型上下文；规模变大后，内部插件市场能分发技能，让成员自行选择安装哪些。

管理「市场」

哪些技能进市场？谁提交？我们没有中央团队拍板，而是尽量让最有用的技能自然浮现。若你想让人试用某个技能，可先上传到 GitHub 的 sandbox 文件夹，在 Slack 等渠道指路。

一旦有了 traction（由技能所有者判断），可提 PR 移入正式市场。

注意：低质量或重复的技能很容易泛滥，正式发布前最好有某种策展机制。

组合技能

你可能需要技能之间相互依赖。例如：一个负责上传文件，一个生成 CSV 并上传。市场与技能系统里尚未原生支持依赖声明，但你可以按名称引用其他技能，若已安装，模型会按需调用。

衡量技能表现

为理解技能使用情况，我们使用 PreToolUse 钩子在公司内记录技能使用（示例代码见原文链接）。由此可发现热门技能，或与预期相比触发不足的技能。

结语

技能是非常强大、灵活的智能体工具，但生态仍早期，我们都在摸索最佳用法。

本文更像是一袋经我们验证有用的技巧，而非唯一权威指南。理解技能最好的方式是：动手做、多实验、找到适合自己的节奏。我们许多技能最初只有几行和一个坑点，正因为大家在 Claude 遇到新边界时持续补充，才越来越好。

作者简介

Thariq Shihipar 现任职于 Anthropic（Claude 的母公司），主要负责 Claude Code 团队——即 Claude 面向代码与代理（agent）能力的产品方向。