Claude Code技能实战：Anthropic内部数百个技能的经验总结

技能（Skills）已成为Claude Code中最常用的扩展点之一。它们灵活、易于创建，且分发简单。但这种灵活性也让人们难以判断什么才是最有效的做法。什么样的技能值得制作？写好一个技能的秘诀是什么？何时与他人分享？

以下是Anthropic内部工程师Thariq整理的一些经验总结。

什么是技能？

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

在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 —— 用于交互式CLI测试（当待验证内容需要TTY时）。

3. 数据获取与分析

连接数据与监控栈的技能。这类技能可能包含获取数据所需的库、凭证、具体的仪表盘ID等，以及常见工作流或获取数据的指引。

示例：

• funnel-query —— “需要关联哪些事件才能看到注册→激活→付费”以及真正包含规范用户ID的表。
• cohort-compare —— 比较两个群组的留存或转化率，标记统计显著的差异，链接到细分定义。
• grafana —— 数据源UID、集群名称、问题→仪表盘查找表。

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

将重复性工作流自动化为一条命令的技能。这类技能通常只是相对简单的指令，但可能依赖于其他技能或MCP（Model Context Protocol）。对于这类技能，将之前的结果保存在日志文件中可以帮助模型保持一致，并能回顾之前执行的工作流。

示例：

• standup-post —— 聚合你的工单追踪、GitHub活动和之前Slack内容 → 格式化的站会更新（仅增量）。
• create-<工单系统>-ticket —— 强制使用规范（有效的枚举值、必填字段）+ 创建后工作流（@评审人、链接到Slack）。
• weekly-recap —— 已合并PR + 已关闭工单 + 部署 → 格式化的周报。

5. 代码脚手架与模板

为代码库中特定功能生成框架样板代码的技能。你可以将这些技能与可组合的脚本结合使用。当你的脚手架有无法完全用代码覆盖的自然语言要求时，这类技能尤其有用。

示例：

• new-<框架>-workflow —— 用你的注解搭建新的服务/工作流/处理器。
• new-migration —— 你的迁移文件模板 + 常见坑点。
• create-app —— 新建内部应用，预置你的认证、日志和部署配置。

6. 代码质量与审查

强制组织内代码质量并帮助审查代码的技能。这些技能可以包含确定性脚本或工具以获得最大稳健性。你可能希望将这些技能作为钩子自动运行，或集成到GitHub Action中。

示例：

• adversarial-review —— 衍生一个“新视角”子Agent进行批判性评审，实施修复，迭代直到发现降级为小问题。
• code-style —— 强制代码风格，特别是Claude默认处理不好的风格。
• testing-practices —— 关于如何编写测试以及测试什么的指引。

7. CI/CD与部署

帮助你在代码库内获取、推送和部署代码的技能。这类技能可能引用其他技能来收集数据。

示例：

• babysit-pr —— 监控PR → 重试不稳定的CI → 解决合并冲突 → 启用自动合并。
• deploy-<服务> —— 构建 → 冒烟测试 → 逐步流量发布，带错误率比较 → 回归自动回滚。
• cherry-pick-prod —— 隔离工作树 → cherry-pick → 解决冲突 → 带模板的PR。

8. 应急手册（Runbooks）

根据症状（如Slack线程、告警或错误特征）引导多工具排查，并生成结构化报告的技能。

示例：

• <服务>-debugging —— 将症状映射到工具→针对最高流量服务的查询模式。
• oncall-runner —— 获取告警 → 检查常见嫌疑点 → 格式化发现。
• log-correlator —— 给定请求ID，拉取可能接触过该请求的每个系统的匹配日志。

9. 基础设施运维

执行日常维护和操作流程的技能——其中一些涉及破坏性操作，因此适合加上防护措施。这类技能让工程师在关键操作中更容易遵循最佳实践。

示例：

• <资源>-orphans —— 查找孤立的Pod/卷 → 发布到Slack → 静默期 → 用户确认 → 级联清理。
• dependency-management —— 你组织的依赖审批工作流。
• cost-investigation —— “为什么我们的存储/出口费用飙升”，附带具体桶和查询模式。

制作技能的技巧

一旦决定了要制作什么技能，如何把它写好？以下是我们总结的一些最佳实践、技巧和窍门。 我们最近还推出了Skill Creator，让在Claude Code中创建技能更加容易。

不要陈述显而易见的内容

Claude Code对你的代码库了解很多，Claude本身也了解大量编程知识，包括许多默认观点。如果你发布的主要是知识类技能，请专注于那些能让Claude跳出常规思维的信息。 frontend-design技能就是一个很好的例子——它由Anthropic的一位工程师通过与客户迭代、改进Claude的设计品味而建立，避免了像Inter字体和紫色渐变这样的常见模式。

建立“坑点”部分

任何技能中信号最强的部分就是“坑点”（Gotchas）。这些部分应该从Claude使用你的技能时常遇到的失败点中积累起来。理想情况下，你会随着时间的推移更新技能，以捕捉这些坑点。

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

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

最简单的渐进式披露形式是指向其他Markdown文件供Claude使用。例如，你可以将详细的函数签名和用法示例拆分到 references/api.md 中。 另一个例子：如果你的最终输出是一个Markdown文件，可以在 assets/ 中包含一个模板文件供复制和使用。 可以有引用、脚本、示例等文件夹，帮助Claude更有效地工作。

避免过度限制Claude

Claude通常会尽力遵循你的指令，而由于技能的可复用性很强，你需要小心不要将指令写得过于具体。给Claude所需的信息，但要让它能灵活适应具体情况。例如：

考虑设置（Setup）

有些技能可能需要用户提供上下文才能设置。例如，如果你制作了一个发布站会更新的技能，你可能希望Claude询问在哪个Slack频道发布。 一个好的模式是将这些设置信息存储在技能目录下的 config.json 文件中，如上例所示。如果配置未设置，Agent就可以询问用户信息。 如果你希望Agent提供结构化的选择题，可以指示Claude使用 AskUserQuestion 工具。

描述字段是为模型准备的

当Claude Code启动一个会话时，它会构建所有可用技能及其描述的列表。Claude扫描这个列表来决定“这个请求有没有对应的技能？”这意味着描述字段不是摘要，而是说明何时应该触发这个技能的指南。

内存与数据存储

一些技能可以通过在内部存储数据来实现某种形式的内存。你可以将数据存储在简单的仅追加文本日志文件、JSON文件，甚至复杂的SQLite数据库中。 例如，standup-post技能可能会保留一个 standups.log 文件，记录每次发布的内容，这样下次运行时，Claude读取自己的历史记录，就能知道自昨天以来发生了什么变化。 注意：存储在技能目录中的数据在技能升级时可能会被删除，因此你应该将数据存储在一个稳定的文件夹中。目前我们提供 ${CLAUDE_PLUGIN_DATA} 作为每个插件稳定存储数据的文件夹。

存储脚本与生成代码

给Claude代码是最强大的工具之一。给Claude脚本和库，可以让Claude把精力花在组合上，决定下一步做什么，而不是重新构造样板代码。 例如，在你的数据科学技能中，你可能有一个函数库用于从事件源获取数据。为了让Claude进行复杂的分析，你可以给它一组辅助函数，就像这样：

然后Claude可以即时生成脚本，组合这些功能，对“周二发生了什么？”这样的提示进行更高级的分析。

按需钩子

技能可以包含仅在技能被调用时激活的钩子，并在会话期间持续存在。当你需要更具倾向性的钩子，但又不想一直运行时，可以使用这些钩子。 例如：

• /careful —— 通过Bash的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、强制推送、kubectl delete。你只在你明确要碰生产环境时才需要它——一直开启会让你抓狂。
• /freeze —— 阻止任何不在特定目录下的编辑/写入操作。在调试时很有用：“我想添加日志，但总是意外‘修复’不相关的东西。”

分发技能

技能的最大好处之一是可以与团队其他成员共享。 有两种方式与他人共享技能：

1. 将技能检入你的代码库（放在 ./.claude/skills 下）。
2. 制作插件，并建立一个Claude Code插件市场，让用户可以上传和安装插件。

对于规模较小、跨仓库较少的团队，将技能检入代码库效果很好。但每个检入的技能也会稍微增加模型的上下文负担。随着规模扩大，内部插件市场可以让你分发技能，并让团队成员决定安装哪些。

管理市场

如何决定哪些技能应该进入市场？人们如何提交技能？ 我们没有集中式的团队来做决定；而是尝试有机地发现最有用的技能。如果你有一个想让别人尝试的技能，可以先上传到GitHub的沙箱文件夹，并在Slack或其他论坛中推广。 一旦某个技能获得了关注（由技能所有者判断），他们可以提交PR将其移至市场。 需要注意的是，创建糟糕或冗余的技能很容易，因此在发布前确保有一定的方法进行筛选很重要。

组合技能

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

衡量技能

为了了解技能的表现，我们使用 PreToolUse 钩子来记录公司内部的技能使用情况。这样我们可以找出哪些技能受欢迎，或者哪些技能触发频率低于预期。