构建 Claude Code 的经验：我们如何使用 Skills
原文链接：claude.com/blog/lesson...
原文作者：Thariq Shihipar
在 Anthropic 内部构建并规模化数百个 Skills 的过程中，我们学到了什么。
Skills 已成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、易于创建，也易于分发。
但正是这种灵活性，让人很难判断什么做法最好：什么样的 Skills 值得做？如何组织一个 Skill？什么时候该与他人共享？
在 Anthropic，我们已在 Claude Code 中大量使用 Skills，活跃使用的数量达数百个。以下是我们用 Skills 加速开发时总结的经验。
什么是 Skills？
Skills 是包含指令、脚本与资源的文件夹，智能体可以发现并使用它们，从而更准确、更高效地完成任务。本文假定读者已了解 Skills 基础；若你是新手，请先从我们的 Skilljar 上的智能体 Skills 入门课程 开始。
关于 Skills，我们常听到一种误解：它们「不过是 Markdown 文件」。实际上，它们是文件夹，可以包含脚本、资产、数据等，供智能体发现、探索与操作。
在 Claude Code 中，Skills 还有 多种配置选项，包括注册动态钩子（hook）。
我们发现，Claude Code 里一些最有效的 Skills，会善用这些配置选项与文件夹结构。
Skills 的类型
在盘点 Anthropic 内部所有 Skills 后，我们发现它们大致可归为九类。最好的 Skills 能清晰归入其中一类；试图做太多事的 Skills 往往会横跨多类，反而让智能体困惑。这不是一份权威清单，但它是识别你自身 Skills 库缺口的实用框架。
Claude Code 团队将内部 Skills 分类，发现可归入九个不同类别。
1. 库与 API 参考
这类 Skills 说明如何正确使用某个库、CLI 或 SDK。既可以是内部库，也可以是 Claude Code 有时处理不好的常见库。这类 Skills 常包含参考代码片段文件夹，以及 Claude 写脚本时应避开的 gotcha 列表。
示例包括：
billing-lib--- 你们内部的计费库：边界情况、踩坑点等。internal-platform-cli--- 内部 CLI 包装器的每个子命令，以及何时使用它们的示例。sandbox-proxy--- 为开发工作配置组织的 egress 网关：哪些主机可达、如何调试「connection refused」错误、如何添加 allowlist 条目。
2. 产品验证
这类 Skills 描述如何测试或验证代码是否正常工作。它们常与 Playwright、tmux 或其他外部验证工具配合使用。
在内部，验证类 Skills 对 Claude 输出质量的可衡量影响最大。让一名工程师花一周时间把验证 Skills 做到优秀，往往是值得的。
可以考虑：让 Claude 录制其输出视频，以便你确切看到它测了什么；或在每一步对状态做程序化断言。这些通常通过在 Skill 中包含多种脚本实现。
示例包括：
signup-flow-driver--- 在无头浏览器中跑完注册 → 邮件验证 → 新手引导，并在每一步用 hook 断言状态。checkout-verifier--- 用 Stripe 测试卡驱动结账 UI，验证发票是否真正进入正确状态。tmux-cli-driver--- 用于交互式 CLI 测试，被验证对象需要 TTY 时使用。
3. 数据获取与分析
这类 Skills 连接你们的数据与监控栈。可能包含带凭据拉取数据的库、特定仪表盘 ID 等，以及常见工作流或取数方式的说明。
示例包括：
funnel-query--- 「要 join 哪些事件才能看 signup → activation → paid」，以及真正存放 canonicaluser_id的表。cohort-compare--- 比较两个 cohort 的留存或转化，标记统计显著差异，并链接到 segment 定义。grafana--- 数据源 UID、集群名、问题 → 仪表盘对照表。datadog--- 字段参考（@request_id与trace_id）、服务列表、指标前缀约定。
4. 业务流程与团队自动化
这类 Skills 把重复工作流自动化为一键命令。通常是指令较简单，但可能更复杂地依赖其他 Skills 或 MCP。对此类 Skills，把历史结果保存在日志文件中，有助于模型保持一致，并反思工作流以往执行。
示例包括：
standup-post--- 汇总工单系统、GitHub 活动与先前 Slack 内容 → 格式化 standup，仅输出 delta。create-<ticket-system>-ticket--- 强制数据结构（合法枚举值、必填字段）及创建后流程（通知审查者、在 Slack 发链接）。weekly-recap--- 已合并 PR + 已关闭工单 + 部署 → 格式化周报。
5. 代码脚手架与模板
这类 Skills 为代码库中特定功能生成框架 boilerplate。可与可组合的脚本 Skills 搭配。当脚手架包含无法纯靠代码覆盖的自然语言要求时尤其有用。
示例包括：
new-<framework>-workflow--- 按你们的注解脚手架新 service/workflow/handler。new-migration--- 迁移文件模板加常见 gotcha。create-app--- 新建内部应用，预置 auth、日志与部署配置。
6. 代码质量与审查
这类 Skills 在组织内强制执行代码质量并辅助审查。可包含确定性脚本或工具以求最大稳健性。你可能希望作为 hook 的一部分，或在 GitHub Action 中自动运行这些 Skills。
adversarial-review--- 派生一个「全新视角」子智能体做批判，实现修复，迭代直到发现退化为吹毛求疵。code-style--- 强制执行代码风格，尤其是 Claude 默认不擅长的风格。testing-practices--- 如何写测试以及测什么的说明。
7. CI/CD 与部署
这类 Skills 帮助在代码库内拉取、推送与部署代码。可能引用其他 Skills 来收集数据。
示例包括：
babysit-pr--- 监控 PR → 重试不稳定 CI → 解决合并冲突 → 启用自动合并。deploy-<service>--- 构建 → 冒烟测试 → 逐步放量并比较错误率 → 回归时自动回滚。cherry-pick-prod--- 隔离 worktree → cherry-pick → 冲突解决 → 带模板的 PR。
8. Runbook（运行手册）
这类 Skills 以症状（如 Slack 线程、告警或错误签名）为输入，走多工具调查，并产出结构化报告。
示例包括：
<service>-debugging--- 为最高流量服务映射 症状 → 工具 → 查询模式。oncall-runner--- 拉取告警 → 检查 usual suspects → 格式化发现。log-correlator--- 给定 request ID，从可能接触过的各系统拉取匹配日志。
9. 基础设施运维
这类 Skills 执行日常维护与运维流程，其中一些涉及破坏性操作，需要护栏。它们让工程师在关键操作上更容易遵循最佳实践。
示例包括：
<resource>-orphans--- 查找孤儿 pod/卷 → 发到 Slack → soak 期 → 用户确认 → 级联清理。dependency-management--- 组织的依赖审批工作流。cost-investigation--- 「存储/egress 账单为何飙升」，含具体 bucket 与查询模式。
制作 Skills 的技巧
决定要做哪个 Skill 之后，怎么写？以下是 Claude Code 团队制作 Skills 的一些最佳实践、技巧与窍门。
不要陈述显而易见之事
Claude 已经会写代码，也能读你的代码库。若一个 Skill 只是复述 Claude 默认会做的事，那就是加了上下文却没加价值。若你发布的是主要关于知识的 Skill，应聚焦能推动 Claude 跳出其常规思路的信息。
frontend design skill 是个好例子：Anthropic 一名工程师与客户迭代，提升 Claude 的设计品味，避免 Inter 字体、紫色渐变等经典套路。
建立 Gotchas 章节
任何 Skill 里信号最强的内容，往往是 Gotchas 章节。这些章节应从 Claude 使用该 Skill 时的常见失败点积累而来。理想情况下，你会随时间更新 Skill 以收录这些 gotcha。
例如：
「subscriptions 表是 append-only。你要的行是 version 最高的那条，不是 created_at 最新的那条。」「该字段在 API gateway 叫 @request_id ，在 billing service 叫 trace_id。它们是同一个值。」「Staging 即使 Stripe webhook 没真正处理也会返回 200。看 payment_events 才是真实状态。」
使用文件系统与渐进式披露（progressive disclosure）
SKILL.md 会指向若干其他文件，供 Claude 在特定情况下参考。例如，若任务 pending，应参考 stuck-jobs.md。
如前所述，Skill 是文件夹，而不只是 Markdown 文件。应把整个文件系统视为一种上下文工程（context engineering）与渐进式披露。告诉 Claude Skill 里有哪些文件，它会在合适时机读取。
渐进式披露最简单的形式，是指向其他 Markdown 文件。例如，把详细函数签名与用法示例拆到 references/api.md。
另一例：若最终输出是 Markdown 文件，可在 assets/ 放模板文件供复制使用。
你可以有 references、scripts、examples 等文件夹，帮助 Claude 更高效工作。
避免过度约束 Claude（railroading）
Claude 一般会尽量遵循你的指令；由于 Skills 高度可复用，你要小心指令过于具体。给 Claude 所需信息，但保留适应情境的灵活性。
例如：
想清楚初始配置
上图 Skill 会在配置未包含 Slack channel 时提示用户。
有些 Skills 需要用户提供上下文才能完成初始配置。例如，若 Skill 要把 standup 发到 Slack，你可能希望 Claude 询问发到哪个频道。
常见做法是把初始配置信息存在 Skill 目录的 config.json 中，如上例。若 config 未配置，智能体再向用户索取信息。
若希望智能体呈现结构化多选题，可指示 Claude 使用 AskUserQuestion 工具。
为模型写描述，不是为人写
Claude Code 启动会话时会构建所有可用 Skills 及其描述的列表。Claude 扫描该列表以判断「有没有适合这个请求的 Skill？」因此描述字段不是摘要，而是何时触发该 Skill 的说明。
在描述里加入 Skill 的触发词（如「babysit」）会很有帮助。
帮助 Claude 记住
该文本日志帮助 Claude 记住过往事件，例如审查 Sarah 的 auth PR。
有些 Skills 可在内部存数据，形成某种记忆。存储介质可以简单到 append-only 文本日志或 JSON，也可以复杂到 SQLite。
例如，standup-post Skill 可能维护 standups.log 记录每次发帖；下次运行时 Claude 读取自己的历史，就能说出与昨天相比有何变化。
可用环境变量 ${CLAUDE_PLUGIN_DATA} 获取稳定目录存放数据；关于在 Skills 中持久化数据的更多说明见：code.claude.com/docs/en/plu...。
存放脚本并生成代码
你能给 Claude 的最强大工具之一是代码。提供脚本与库，让 Claude 把回合用在组合与决定下一步，而不是重建 boilerplate。
例如，在 data-science Skill 中，你可以有从事件源拉取数据的函数库。为让 Claude 做复杂分析，可给它一组 helper 函数，如下：
Claude 随后可即时生成脚本，组合这些能力，回答如「周二发生了什么？」这类 prompt。
使用按需 hook
Skills 可包含仅在 Skill 被调用时激活、且仅持续该会话的 hook。用于那些你不想一直开着、但有时极其有用的更强 opinionated hook。
例如：
/carefulrm -rf、DROP TABLE、force-push、kubectl delete。只有确定要动 prod 时才需要------一直开着会让人抓狂。/freeze--- 阻止对特定目录外任何 Edit/Write。调试时有用：「我想加日志，但老是不小心『修』无关代码。」
分发 Skills
Skills 最大好处之一，是可以与团队共享。
与他人共享 Skills 大致有两种方式：
- 把 Skills 提交到仓库（位于
./.claude/skills） - 做成 plugin ，并建立 Claude Code Plugin marketplace，供用户上传与安装插件（详见 文档）
对小团队、跨较少 repo 的场景，把 Skills 提交到 repo 很合适。但每个提交的 Skill 也会略增模型的上下文负担。规模变大后，内部 plugin marketplace 可分发 Skills，让团队自行选择安装哪些，并包含初始配置流程。
管理 Skills marketplace
如何决定哪些 Skills 进入 marketplace？人们如何提交？
在 Anthropic，我们没有集中决策团队拍板；而是尽量自然生长出最有用的 Skills。若有人希望他人试用某个 Skill，可上传到 GitHub 的 sandbox 文件夹，并在 Slack 或其他论坛指向它。
一旦 Skill 获得足够采用（由 Skill 所有者自行判断），可提 PR 将其移入 marketplace。
组合 Skills
你可能希望 Skills 彼此依赖。例如，一个上传文件的 Skill，与一个生成 CSV 并上传的 Skill。这类依赖管理尚未原生内建于 marketplace 或 Skills，但你可以按名称引用其他 Skills，若已安装，模型会调用它们。
衡量 Skills
要了解 Skill 表现如何，我们使用 PreToolUse hook 在公司内记录 Skill 使用情况（示例代码在此）。这样可找出热门 Skills，或与预期相比触发不足的 Skills。
开始使用
Skills 最佳实践仍在演进。我们最好的 Skills 大多从几行加一个 gotcha 起步，随着 Claude 遇到新边界情况，人们不断补充而变好。
理解 Skills 最好的方式是动手：开始、实验，看什么对你有效。
本文由 Anthropic 技术团队成员、Claude Code 工程师 Thariq Shihipar 撰写。