构建 Claude Code 的经验教训：我们如何使用Skills｜Anthropic

Created time

Apr 1, 2026 08:21 AM

构建 Claude Code 的经验教训：我们如何使用Skills

Skills（技能）已成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、易于创建且分发简单。

我们在 Anthropic 内部一直在广泛使用 Claude Code 的技能，目前有数百个技能处于活跃使用状态。以下是我们关于利用技能来加速开发所总结出的经验教训。

什么是技能 (Skills)？

如果你还不了解技能，我建议阅读我们的文档或者观看我们关于智能体技能（Agent Skills）的最新课程。本文假设你已经对技能有了一定的了解。

关于技能，我们常听到一个常见的误解，即它们“只是 Markdown 文件”。但技能最有趣的地方在于，它们不仅仅是文本文件。它们是包含脚本、资源、数据等的文件夹，智能体可以对其进行发现、探索和操作。

我们发现，Claude Code 中一些最有趣的技能，都巧妙地运用了这些配置选项和文件夹结构。

技能类型

1. 库与 API 参考

这些技能解释了如何正确使用库、CLI 或 SDK。它们既适用于内部库，也适用于 Claude Code 有时难以处理的常用库。这些技能通常包含一个参考代码片段文件夹，以及一份 Claude 在编写脚本时需要避免的“避坑指南”。

示例：

billing-lib —— 你们的内部计费库：边缘情况、隐患（footguns）等。

internal-platform-cli —— 你内部 CLI 封装工具的每一个子命令，并附带使用场景示例。

frontend-design —— 让 Claude 更擅长运用你的设计系统。

2. 产品验证

描述如何测试或验证代码是否正常工作的技能。这些技能通常会与 Playwright、tmux 等外部工具配合使用，以进行验证。

验证技能对于确保 Claude 输出的准确性极其有用。花一周时间让工程师专门打磨你的验证技能，绝对物有所值。

可以考虑一些技巧，比如让 Claude 录制其输出的视频，这样你就能清楚看到它具体测试了什么；或者在每一步强制执行程序化的状态断言。这些通常可以通过在技能中包含各种脚本来实现。

示例：

checkout-verifier —— 使用 Stripe 测试卡驱动结账 UI，并验证发票是否确实处于正确状态。

tmux-cli-driver —— 用于交互式 CLI 测试，适用于需要 TTY 环境的验证场景。

3. 数据获取与分析

连接到你的数据和监控堆栈的技能。这些技能可能包括用于凭据获取数据的库、特定的仪表板 ID 等，以及关于常见工作流程或获取数据方式的说明。

示例：

cohort-compare —— 比较两个群组的留存率或转化率，标记具有统计学意义的差异，并链接到细分定义。

grafana —— 数据源 UID、集群名称、问题 → 仪表盘查询表。

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

将重复性工作流自动化为单一指令的技能。这些技能通常是相当简单的指令，但也可能对其他技能或 MCP 存在更复杂的依赖关系。对于这些技能，将过往结果保存到日志文件中，可以帮助模型保持一致性，并对工作流的过往执行情况进行反思。

示例：

standup-post —— 汇总你的工单追踪器、GitHub 活动和之前的 Slack 记录 → 生成格式化的站会日报，仅包含增量更新。

create-<ticket-system>-ticket —— 强制执行模式（有效的枚举值、必填字段）以及创建后的工作流（提醒审核人、在 Slack 中关联）。

weekly-recap —— 合并的 PR + 关闭的工单 + 部署 → 格式化的回顾帖。

5. 代码脚手架与模板

用于在代码库中为特定功能生成框架样板代码的技能。你可以将这些技能与可组合的脚本结合使用。当你的脚手架包含无法仅通过代码完全覆盖的自然语言需求时，它们会特别有用。

示例：

new-<framework>-workflow —— 使用你的注解来构建一个新的服务/工作流/处理器。

new-migration —— 你的迁移文件模板及常见避坑指南。

create-app —— 预置了你的身份验证、日志记录和部署配置的全新内部应用。

6. 代码质量与审查

在组织内部强制执行代码质量并辅助代码审查的技能。这些技能可以包含确定性脚本或工具，以实现最大程度的稳健性。你可能希望将这些技能作为钩子（hooks）的一部分或在 GitHub Action 中自动运行。

示例：

adversarial-review（对抗性审查）—— 启动一个全新的子智能体进行批判性评估，实施修复，并不断迭代，直到问题仅剩下细枝末节。

code-style —— 强制执行代码风格，尤其是那些 Claude 默认处理得不够好的风格。

testing-practices —— 关于如何编写测试以及测试内容的说明。

7. CI/CD 与部署

能够帮助你在代码库中获取、推送和部署代码的技能。这些技能可能会调用其他技能来收集数据。

示例：

babysit-pr —— 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 开启自动合并。

deploy-<service> —— 构建 → 冒烟测试 → 结合错误率对比的灰度发布 → 回归问题自动回滚。

cherry-pick-prod —— 隔离的工作树 → 拣选（cherry-pick） → 冲突解决 → 带有模板的 PR。

8. 运行手册 (Runbooks)

能够处理各类症状（如 Slack 讨论串、警报或错误特征）的技能，通过多工具排查流程，最终生成结构化报告。

示例：

<service>-debugging —— 将症状映射至工具及查询模式，适用于您流量最高的各项服务。

oncall-runner —— 获取警报 → 检查常见问题源 → 格式化调查结果。

log-correlator —— 给定一个请求 ID，从可能接触过该请求的每个系统中提取匹配的日志。

9. 基础设施运维

执行日常维护和操作程序的技能——其中一些涉及破坏性操作，需要护栏保护。这些技能使工程师在执行关键操作时更容易遵循最佳实践。

示例：

<resource>-orphans —— 查找孤立的 pod/卷 → 发布到 Slack → 观察期 → 用户确认 → 级联清理。

dependency-management —— 你们组织的依赖审批工作流。

cost-investigation —— “为什么我们的存储/流出费用激增”，附带特定的存储桶和查询模式。

制作技能的技巧

一旦你决定了要制作什么技能，该如何编写它呢？以下是我们发现的一些最佳实践、提示和技巧。

我们最近还发布了 Skill Creator，让在 Claude Code 中创建技能变得更加容易。

不要陈述显而易见的事实

Claude Code 对你的代码库了如指掌，Claude 本身也精通编程，包括许多默认观点。如果你发布的技能主要是关于知识的，请尝试专注于那些能让 Claude 跳出常规思维模式的信息。

前端设计技能就是一个很好的例子。它是 Anthropic 的一位工程师通过与客户不断迭代，改进了 Claude 的设计品味，避免了像 Inter 字体和紫色渐变这样的经典模式。

建立“避坑指南”部分

任何技能中信号量最高的内容都是“避坑指南”（Gotchas）部分。这些内容应该基于 Claude 在使用你的技能时遇到的常见失败点。理想情况下，你应该随着时间的推移不断更新技能，以捕捉这些坑。

利用文件系统和渐进式披露

正如我们之前所说，技能是一个文件夹，而不仅仅是一个 Markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式披露的形式。告诉 Claude 你的技能中有哪些文件，它会在适当的时候读取它们。

渐进式披露最简单的形式是让 Claude 指向其他 Markdown 文件。例如，你可以将详细的函数签名和使用示例拆分到 references/api.md 中。

另一个例子：如果你的最终输出是一个 Markdown 文件，你可以在 assets/ 中包含一个模板文件供其复制使用。

你可以拥有参考资料、脚本、示例等文件夹，这有助于 Claude 更有效地工作。

避免限制 Claude 的思路

Claude 通常会努力遵守你的指令。由于技能的复用性很高，你要注意不要在指令中写得过于死板。给 Claude 提供它需要的信息，但也要给它根据情况进行调整的灵活性。例如：

考虑好设置流程

某些技能可能需要用户提供上下文进行设置。例如，如果你正在制作一个将站会内容发布到 Slack 的技能，你可能希望 Claude 询问要发布到哪个 Slack 频道。

一个好的模式是将这些设置信息存储在技能目录下的 config.json 文件中，如上例所示。如果配置未设置，智能体可以询问用户。

如果你希望智能体呈现结构化的多项选择题，可以指示 Claude 使用 AskUserQuestion 工具。

描述字段是给模型看的

当 Claude Code 开始一个会话时，它会列出所有可用技能及其描述。Claude 会扫描这个列表来决定“是否有适合此请求的技能？”这意味着描述字段不是摘要，而是关于何时触发该技能的说明。

记忆与数据存储

某些技能可以通过在内部存储数据来实现某种形式的记忆。你可以将数据存储在任何东西中，从简单的追加式文本日志文件或 JSON 文件，到复杂的 SQLite 数据库。

例如，standup-post 技能可以保留一个 standups.log，记录它写过的每一篇帖子。这意味着下次运行它时，Claude 会读取自己的历史记录，并能分辨出从昨天以来发生了什么变化。

技能目录中存储的数据可能会在升级技能时被删除。因此你应该将其存储在稳定文件夹中。目前，我们为每个插件提供 ${ CLAUDE_PLUGIN_DATA } 作为稳定文件夹来存储数据。

存储脚本并生成代码

你能给 Claude 最强大的工具之一就是代码。为 Claude 提供脚本和库，可以让它把精力花在组合逻辑和决定下一步该做什么上，而不是去重构样板代码。

例如，在你的数据科学技能中，你可能有一个从事件源获取数据的函数库。为了让 Claude 进行复杂的分析，你可以给它一套辅助函数，如下所示：

随后，Claude 就可以即时生成脚本来组合这些功能，从而针对“周二发生了什么？”之类的提示进行更高级的分析。

按需钩子 (Hooks)

技能可以包含仅在调用该技能时激活并持续到会话结束的钩子。对于那些你不想一直运行、但在某些时候极其有用的特定钩子，可以使用此功能。

例如：

/ careful —— 通过 Bash 上的 PreToolUse 匹配器拦截 rm -rf、DROP TABLE、强制推送、kubectl delete。你只有在知道自己正在操作生产环境时才需要这个功能——如果一直开启，会让人发疯。

/ freeze —— 拦截任何不在特定目录下的编辑/写入操作。非常有用。

分发技能

将你的技能检入仓库（在 ./.claude/skills 下）。

制作插件，并建立一个 Claude Code 插件市场，用户可以在其中上传和安装插件（在此处阅读更多文档）。

对于在较少仓库中工作的小型团队，将技能检入仓库效果很好。但每个检入的技能也会增加模型的上下文负担。随着规模扩大，内部插件市场允许你分发技能，并让你的团队决定安装哪些技能。

管理市场

你如何决定哪些技能进入市场？人们如何提交它们？

我们没有一个集中的团队来决定；相反，我们尝试有机地发现最有用的技能。如果你有一个想让大家尝试的技能，可以将其上传到 GitHub 的沙盒文件夹中，并在 Slack 或其他论坛中指引大家使用。

一旦某个技能获得了关注（由技能所有者决定），他们可以提交 PR 将其移入市场。

需要提醒的是，创建糟糕或冗余的技能非常容易，因此在发布前确保有某种审核机制非常重要。

组合技能

你可能希望技能之间存在依赖关系。例如，你可能有一个上传文件的技能，以及一个生成 CSV 并上传它的技能。这种依赖管理尚未原生内置在市场或技能中，但你可以直接按名称引用其他技能，如果已安装，模型就会调用它们。

衡量技能

结论

对于智能体来说，技能是极其强大且灵活的工具，但现在还处于早期阶段，我们都在探索如何最好地使用它们。

与其说这是一份权威指南，不如说它是我们见证过有效的一系列实用技巧。理解技能的最佳方式是开始行动、实验并观察什么对你有效。我们的许多技能最初只有几行字和一个“避坑指南”，随着人们在 Claude 遇到新的边缘情况时不断补充，它们变得越来越完善。

希望这有所帮助，如有任何问题请告诉我。