【译】构建 Claude Code 的经验：我们如何使用 Skills
原文：Lessons from Building Claude Code: How We Use Skills 作者：Thariq 发布日期：2026 年 4 月 3 日
Skills 已成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、易于构建且分发简单。
但这种灵活性也让人难以把握最佳实践。什么样的 Skills 值得构建？编写高质量 Skill 的秘诀是什么？什么时候该与他人分享？
在 Anthropic，我们一直在深度使用 Claude Code 的 Skills，目前有数百个正在活跃使用中。以下是我们在利用 Skills 加速开发过程中总结的经验。
如果你是初次接触 Skills，建议先阅读文档或观看我们的最新课程 — 本文将假设你已经对 Skills 有一定了解。
关于 Skills，我们常听到一个误解，认为它们”只是 markdown 文件”。但 Skills 最有趣的地方在于它们不仅是文本文件，而是包含脚本、资产、数据等的文件夹，Agent 可以发现、探索并操作其中的内容。
在 Claude Code 中，Skills 还包含一个配置文件，用于注册动态 Hook（钩子）。
我们发现，Claude Code 中一些最引人注目的 Skills 都创造性地利用了这些配置选项和文件夹结构。
在对我们所有的 Skills 进行分类后，我们注意到它们可以归纳为几个反复出现的类别。最优秀的 Skills 通常能清晰地归入某一类；而那些让人困惑的则往往跨越多个类别。这并非一份最终名单，但它可以帮你思考团队中是否还缺少某些类型。
库/SDK 类 Skills
这类 Skills 解释了如何正确使用某个库、CLI 或 SDK。它们既可以针对内部库，也可以针对 Claude Code 有时难以处理的通用库。这些 Skills 通常包含一个参考代码片段文件夹，以及一份供 Claude 在编写脚本时参考的踩坑点（gotchas）清单。
示例：
- billing-lib → 你的内部计费库：边界情况、容易踩坑的地方等。
- internal-platform-cli → 内部 CLI 封装器的每个子命令，以及何时使用它们的示例。
- frontend-design → 让 Claude 更好地理解你的设计系统。
验证类 Skills
这类 Skills 描述了如何测试或验证代码是否正常运行。它们通常与 Playwright、tmux 等外部工具配合使用进行验证。
验证类 Skills 对于确保 Claude 的输出正确极其有用。值得投入一名工程师一整周的时间来打磨验证类 Skills。
可以尝试一些技术，比如让 Claude 录制其输出的视频，以便你确切看到它测试了什么，或者在每一步强制执行状态的程序化断言。这些通常通过在 Skill 中包含各种脚本来实现。
示例：
- signup-flow-driver → 在无头浏览器中运行从注册到邮件验证再到入职的流程，并配有用于在每一步断言状态的 Hook。
- checkout-verifier → 使用 Stripe 测试卡驱动结账 UI，验证发票是否真正进入正确状态。
- tmux-cli-driver → 用于交互式 CLI 测试，适用于需要 TTY 才能验证的场景。
数据与监控类 Skills
这类 Skills 连接到你的数据和监控栈。它们可能包含带有凭证的取数库、特定的仪表板 ID，以及常见工作流或取数方式的指令。
示例：
- funnel-query → “哪些事件需要关联才能看到从注册到激活再到付费的转化”，以及真正拥有规范
user_id的表。 - cohort-compare → 比较两个群组的留存或转化情况，标记具有统计学显著性的差异，并链接到分群定义。
- grafana → 数据源 UID、集群名称、问题到仪表板的查找表。
工作流自动化类 Skills
这类 Skills 将重复的工作流自动化为一条命令。它们通常包含相当简单的指令，但可能对其他 Skills 或 MCP 有更复杂的依赖。对于这类 Skills，将之前的结果保存在日志文件中可以帮助模型保持一致性，并反思该工作流之前的执行情况。
示例：
- standup-post → 聚合你的工单追踪器、GitHub 活动以及之前的 Slack 消息，生成格式化的每日站报，仅显示差异。
- create-<ticket-system>-ticket → 强制执行 Schema（有效的枚举值、必填字段）以及创建后的工作流（提醒评审人员、在 Slack 中分享链接）。
- weekly-recap → 已合并的 PR + 已关闭的工单 + 部署情况 → 格式化的每周回顾贴。
脚手架类 Skills
这类 Skills 为代码库中的特定功能生成框架样板代码。你可以将这些 Skills 与可组合的脚本结合使用。当你的脚手架具有无法单纯靠代码覆盖的自然语言要求时，它们尤其有用。
示例：
- new-<framework>-workflow → 使用你的注解为新服务/工作流/处理程序生成脚手架。
- new-migration → 你的迁移文件模板以及常见的踩坑点。
- create-app → 预先配置好你的鉴权、日志和部署配置的新内部应用。
代码评审类 Skills
这类 Skills 用于在组织内部强制执行代码质量并辅助代码评审。为了最大限度的健壮性，它们可以包含确定性的脚本或工具。你可能希望将这些 Skills 作为 Hook 的一部分或在 GitHub Action 中自动运行。
示例：
- adversarial-review → 派出一个视角清新的子 Agent 进行批判性评审，实施修复，不断迭代直到问题只剩吹毛求疵的细节。
- code-style → 强制执行代码风格，特别是 Claude 默认做得不够好的风格。
- testing-practices → 关于如何编写测试以及测试什么的指令。
Git 与部署类 Skills
这类 Skills 帮你获取、推送和部署代码库中的代码。它们可能会引用其他 Skills 来收集数据。
示例：
- babysit-pr → 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 开启自动合并。
- deploy-<service> → 构建 → 冒烟测试 → 带有错误率对比的渐进式流量发布 → 出现回退时自动回滚。
- cherry-pick-prod → 隔离的工作树 → cherry-pick → 冲突解决 → 带有模板的 PR。
排查类 Skills
这类 Skills 接收症状（如 Slack 讨论串、警报或错误特征码），执行多工具协作调查，并生成结构化报告。
示例：
- <service>-debugging → 为你的高流量服务映射症状、工具以及查询模式。
- oncall-runner → 获取警报 → 检查常见疑点 → 格式化发现结果。
- log-correlator → 给定一个请求 ID，从每一个可能接触过该请求的系统中提取匹配的日志。
维护类 Skills
这类 Skills 执行例行维护和操作程序，其中一些涉及需要护栏的破坏性操作。这使得工程师在关键操作中更容易遵循最佳实践。
示例：
- <resource>-orphans → 查找孤立的 Pod/卷 → 发布到 Slack → 观察期 → 用户确认 → 级联清理。
- dependency-management → 组织内部的依赖审批工作流。
- cost-investigation → “为什么我们的存储/流出账单激增”，并附带特定的存储桶和查询模式。
如何编写优秀的 Skills
一旦决定了要制作什么 Skill，该如何编写呢？以下是我们发现的一些最佳实践、提示和技巧。
我们最近还发布了一个 Skill 生成器，让在 Claude Code 中创建 Skills 变得更加容易。
专注于非默认知识
Claude Code 对你的代码库非常了解，而 Claude 本身对编程也很有经验，包括许多默认观点。如果你发布的 Skill 主要是关于知识的，重点放在那些能让 Claude 跳出常规思维模式的信息。
frontend-design 这个 Skill 就是一个很好的例子 — 它是由 Anthropic 的一位工程师通过与客户反复迭代构建的，旨在提升 Claude 的设计品味，避免使用 Inter 字体和紫色渐变等俗套模式。
踩坑点具有高信号价值
任何 Skill 中信号价值最高的内容就是踩坑点（Gotchas）部分。这些内容应该根据 Claude 在使用你的 Skill 时遇到的常见失败点逐步构建。理想情况下，你应该随着时间的推移不断更新 Skill，以捕获这些新发现的踩坑点。
利用文件夹结构实现渐进式披露
正如我们前面所说，Skill 是一个文件夹，而不仅仅是一个 markdown 文件。你应该将整个文件系统视为上下文工程（context engineering）和渐进式披露的一种形式。告诉 Claude 你的 Skill 中包含哪些文件，它会在合适的时候读取它们。
渐进式披露最简单的形式是引导 Claude 使用其他的 markdown 文件。例如，你可以将详细的函数签名和使用示例拆分到 references/api.md 中。
另一个例子：如果你的最终输出是一个 markdown 文件，你可以在 assets/ 中包含一个模板文件供其复制使用。
你可以建立参考资料、脚本、示例等文件夹，这有助于 Claude 更有效地工作。
保持灵活性，而非死板
Claude 通常会尝试严格遵守你的指令，但由于 Skills 的可复用性很高，你需要警惕指令过于具体。给 Claude 所需的信息，但给它根据具体情况进行调整的灵活性。例如：
将用户设置存储在配置中
有些 Skills 可能需要根据用户的上下文进行设置。例如，如果你正在制作一个将站报发布到 Slack 的 Skill，你可能希望 Claude 询问该发布到哪个 Slack 频道。
一种很好的模式是将这些设置信息存储在 Skill 目录下的 config.json 文件中，如上例所示。如果配置未设置，Agent 随后可以向用户询问信息。
如果希望 Agent 呈现结构化的选择题，可以指示 Claude 使用 AskUserQuestion 工具。
编写高质量的描述
当 Claude Code 启动会话时，它会建立一个包含所有可用 Skill 及其描述的列表。Claude 会扫描这个列表来决定”是否有处理该请求的 Skill？“这意味着描述字段不是摘要，而是关于何时触发该 Skill 的说明。
将 Skill 作为记忆载体
有些 Skills 可以通过在内部存储数据来实现某种形式的记忆。你可以存储在像追加式文本日志文件或 JSON 文件这样简单的载体中，也可以存储在像 SQLite 数据库这样复杂的载体中。
例如，一个 standup-post Skill 可能会保留一份 standups.log，记录它写过的每一篇帖子。这意味着下次你运行它时，Claude 会读取自己的历史记录，并能分辨出从昨天到现在发生了什么变化。
存储在 Skill 目录中的数据可能会在你升级 Skill 时被删除，因此你应该将其存储在稳定文件夹中。目前我们提供了 ${CLAUDE_PLUGIN_DATA} 作为一个稳定的插件数据存储文件夹。
包含脚本和库
你能给 Claude 提供的最强大的工具之一就是代码。提供脚本和库让 Claude 可以将回合花在编排上，决定下一步该做什么，而不是重构样板代码。
例如，在你的数据科学 Skill 中，你可能有一个从事件源提取数据的函数库。为了让 Claude 进行复杂的分析，你可以给它一组如下所示的辅助函数：
Claude 随后可以即时生成脚本来编排这些功能，从而针对”周二发生了什么？“之类的 Prompt 进行更高级的分析。
使用会话级别的 Hook
Skills 可以包含仅在调用该 Skill 时激活，并持续到会话结束的 Hook。这适用于那些你不想一直运行、但在某些特定时刻非常有用的强主见 Hook。
例如：
/careful→ 通过在 Bash 上设置 PreToolUse 匹配器，拦截rm -rf、DROP TABLE、force-push和kubectl delete。你只在知道自己要动生产环境时才需要它 — 如果一直开启，会让你崩溃。/freeze→ 拦截任何不在特定目录下的 Edit/Write 操作。在调试时很有用：“我想加点日志，但我老是不小心’顺便修复’了不相关的代码”。
与团队分享 Skills
Skills 的最大优势之一是你可以将它们分享给团队的其他成员。
有两种与他人分享 Skills 的方式：
- 将你的 Skills 签入代码库（放在
./.claude/skills下）。 - 制作插件，并通过 Claude Code 插件市场供用户上传和安装。
对于在相对较少的库中工作的小型团队，将 Skills 签入库中效果很好。但签入的每个 Skill 也会增加模型的上下文负担。随着规模扩大，内部插件市场允许你分发 Skills，并让团队决定安装哪些。
如何筛选 Skills
你如何决定哪些 Skills 进入市场？人们如何提交它们？
我们没有一个中心化的团队来决定；相反，我们尝试有机地发现最有用的 Skills。如果你有一个想让大家尝试的 Skill，你可以将其上传到 GitHub 的 sandbox 文件夹，并在 Slack 或其他论坛中指引大家。
一旦某个 Skill 获得了认可（这由 Skill 所有者决定），他们可以提交 PR 将其移入市场。
需要提醒的是，创建糟糕或冗余的 Skills 相当容易，因此确保在发布前有一定的筛选机制非常重要。
Skill 依赖关系
你可能希望 Skills 之间存在依赖关系。例如，你可能有一个上传文件的 Skill，以及一个生成 CSV 并调用上传 Skill 的 Skill。这类依赖管理尚未原生集成到市场或 Skills 中，但你只需通过名称引用其他 Skills，如果已安装，模型就会调用它们。
衡量 Skill 使用情况
为了了解一个 Skill 的表现，我们使用 PreToolUse Hook 来记录公司内部的 Skill 使用情况。这意味着我们可以发现那些受欢迎的 Skills，或者那些触发频率低于我们预期的 Skills。
结论
对于 Agent 来说，Skills 是极其强大、灵活的工具，但目前尚处于早期阶段，我们都在摸索如何最佳地使用它们。
与其将这看作是一份权威指南，不如将其看作是一组我们亲测有效的实用技巧。理解 Skills 的最佳方式是开始行动、动手实验，看看什么对你最有效。我们的多数 Skills 最初都只有几行代码和一个踩坑点，随着人们在 Claude 遇到新的边界情况时不断增补，它们才变得越来越好。
希望这些内容对你有所帮助，如有任何问题请随时告诉我。
