构建Claude Code的经验：技能分类与应用技巧

从构建Claude Code中学到的：我们如何使用技能

### 技能类型 在Anthropic内部盘点所有技能后，我们发现它们可以归为九类。最好的技能恰好属于其中一类；而那些试图涵盖太多内容的技能会跨越多个类别，从而让智能体感到困惑。这不是一个权威列表，但它是一个有用的框架，可以帮助你发现自己技能库中的空白。Claude Code团队将内部技能分类后，发现可以归为九个不同的类别。

#### 1. 库与API参考 这类技能用于解释如何正确使用某个库、CLI或SDK。它们既可以针对内部库，也可以针对Claude Code有时难以处理的常见库。这些技能通常包含一个参考代码片段文件夹，以及一份Claude在编写脚本时应避免的陷阱列表。

示例包括： - billing-lib — 你的内部计费库：边界情况、陷阱等。 - internal-platform-cli — 内部CLI封装器的每个子命令，附有使用场景示例。 - sandbox-proxy — 配置组织的开发环境出口网关：哪些主机可达、如何调试“连接被拒绝”错误、如何添加允许列表条目。

#### 2. 产品验证 这类技能描述了如何测试或验证代码是否正常工作。它们通常与playwright、tmux或其他外部验证工具配合使用。

验证技能对内部Claude输出质量的影响最为显著。值得让一位工程师花一周时间专门优化你的验证技能。

可以考虑让Claude记录其输出的视频，以便你准确查看它测试了什么，或者在每一步强制进行程序化状态断言。这些通常通过在技能中包含各种脚本实现。

示例包括： - signup-flow-driver — 在无头浏览器中执行注册→邮箱验证→引导流程，并在每一步设置状态断言钩子。 - checkout-verifier — 使用Stripe测试卡驱动结账UI，验证发票是否确实到达正确状态。 - tmux-cli-driver — 用于交互式CLI测试，当验证目标需要TTY时。

#### 3. 数据获取与分析 这类技能连接到你的数据和监控栈。这些技能可能包含用于获取数据的库（含凭证）、特定仪表板ID等，以及常见工作流或数据获取方法的说明。

示例包括： - funnel-query — “我需要连接哪些事件才能看到注册→激活→付费”，以及包含规范user_id的表。 - cohort-compare — 比较两个队列的留存率或转化率，标记统计显著差异，链接到分群定义。 - grafana — 数据源UID、集群名称、问题→仪表板查找表。 - datadog — 字段参考（@request_id vs trace_id）、服务列表、指标前缀约定。

#### 4. 业务流程与团队自动化 这类技能将重复性工作流程自动化成一个命令。这些技能通常相当简单，但可能依赖其他技能或MCP，较为复杂。对于这些技能，将先前结果保存到日志文件有助于模型保持一致性，并能回顾之前的工作流执行情况。

示例包括： - standup-post — 聚合你的工单跟踪器、GitHub活动和过去的Slack，生成格式化的站会报告，仅显示增量。 - create-<ticket-system>-ticket — 强制遵循模式（有效枚举值、必填字段），并包含创建后工作流（@提醒审阅者、在Slack中链接）。 - weekly-recap — 合并的PR + 关闭的工单 + 部署 → 格式化的周总结。

#### 5. 代码脚手架与模板 这类技能为代码库中的特定功能生成框架样板。你可以将这些技能与可组合的脚本结合使用。当你的脚手架包含无法纯粹通过代码覆盖的自然语言需求时，它们尤其有用。

示例包括： - new-<framework>-workflow — 使用你的注解搭建新的服务/工作流/处理器。 - new-migration — 迁移文件模板及常见陷阱。 - create-app — 预接入认证、日志和部署配置的新内部应用。

#### 6. 代码质量与审查 这类技能用于在你的组织内实施代码质量并辅助代码审查。它们可以包含确定性脚本或工具以实现最大稳健性。你可能希望将这些技能作为钩子的一部分或在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. 运行手册 这类技能接受一个症状（如Slack线索、告警或错误签名），执行多工具调查，并生成结构化报告。

示例包括： - <service>-debugging — 将症状映射到你最高流量服务的工具和查询模式。 - oncall-runner — 获取告警 → 检查常见嫌疑人 → 格式化发现结果。 - log-correlator — 给定请求ID，从可能接触过的每个系统中拉取匹配的日志。

#### 9. 基础设施运维 这类技能执行日常维护和运维流程，其中一些涉及破坏性操作，需要防护措施。它们帮助工程师在关键操作中遵循最佳实践。

示例包括： - <resource>-orphans — 发现孤立的Pod/卷 → 发布到Slack → 等待确认 → 级联清理。 - dependency-management — 你组织的依赖审批工作流。 - cost-investigation — “为什么我们的存储/出口费用飙升”，附带具体桶和查询模式。

### 创建技巧 一旦决定了要创建什么技能，该如何编写呢？以下是Claude Code团队的一些最佳实践、技巧和窍门。

#### 不要陈述显而易见的内容 Claude已经知道如何编码，并且可以阅读你的代码库。一个重述Claude默认行为的技能只会增加上下文，而不会增加价值。如果你发布的技能主要是知识性的，请专注于能让Claude跳出常规思维的信息。

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

#### 建立一个“陷阱”章节 任何技能中最有价值的内容就是“陷阱”章节。这些章节应该基于Claude在使用你的技能时遇到的常见失败点来构建。理想情况下，你会随时间更新技能，以捕捉这些陷阱。

例如： - “订阅表是仅追加的。你需要的行是版本号最高的那一行，而不是created_at最新的那一行。” - “这个字段在API网关中叫@request_id，在计费服务中叫trace_id。它们是同一个值。” - “即使Stripe webhook实际上没有处理，Staging也返回200。请检查payment_events表以获取真实状态。”

#### 使用文件系统和渐进式披露 SKILL.md文件指向其他几个文件，Claude可以在特定情况下引用它们。例如，如果某个任务处于挂起状态，它应该引用stuck-jobs.md。

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

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

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

你可以有引用、脚本、示例等文件夹，这些都能帮助Claude更有效地工作。

#### 避免过度限制Claude Claude通常会尽量遵循你的指令，由于技能的可重用性很高，你要小心指令不要过于具体。给Claude所需的信息，但给予它适应情况的灵活性。

例如：

#### 思考设置过程 上面的技能旨在提示用户，如果Slack频道未包含在配置中。

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

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

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

#### 为模型编写描述，而不是为人类 当Claude Code启动一个会话时，它会构建每个可用技能及其描述的列表。这个列表是Claude扫描以决定“这个请求是否有对应的技能？”的依据。这意味着描述字段不是一个摘要，而是一个何时触发此技能的描述。

在描述中包含技能的触发词（如“babysit”）是有帮助的。

#### 帮助Claude记忆 这个文本日志文件帮助Claude记住过去的事件，比如审查Sarah的auth PR。

某些技能可以通过在自身内部存储数据来包含一种记忆形式。你可以将数据存储在简单如仅追加的文本日志文件或JSON文件中，也可以复杂如SQLite数据库中。

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

你可以使用环境变量${CLAUDE_PLUGIN_DATA}来获取一个稳定的目录来存储数据，更多关于在技能中持久化数据的信息，请参阅文档。

#### 存储脚本并生成代码 你可以给Claude的最强大的工具之一是代码。给Claude脚本和库，可以让Claude将它的计算回合花在组合上，决定下一步做什么，而不是重新构建样板代码。

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

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

#### 使用按需钩子 技能可以包含仅在技能被调用时才激活的钩子，并且这些钩子只在会话期间有效。使用这些钩子来实现那些你不想一直运行、但有时极其有用的更有主见的钩子。

例如： - /careful — 通过PreToolUse匹配器在Bash中阻止rm -rf、DROP TABLE、强制推送、kubectl delete。你只希望在你知道正在接触生产环境时才启用它——一直开着会让人发疯。 - /freeze — 阻止任何不在特定目录中的编辑/写入操作。在调试时很有用：“我想添加日志，但我总是意外地“修复”不相关的代码。”

### 分发技能 技能的最大好处之一是可以与团队其他成员分享。

有两种方式分享技能： - 将技能检入你的代码库（放在./.claude/skills下）。 - 制作一个插件，并拥有一个Claude Code插件市场，用户可以在其中上传和安装插件（更多信息请阅读文档）。

对于在相对较少的代码库上工作的小团队，将技能检入代码库效果不错。但每个检入的技能也会给模型增加一点上下文。随着规模扩大，内部插件市场允许你分发技能，让团队自行决定安装哪些技能，并包含设置流程。

### 管理技能市场 如何决定哪些技能进入市场？人们如何提交？

在Anthropic，我们没有集中的团队来决定；相反，我们尝试有机地找到最有用的技能。如果有人有一个希望别人尝试的技能，他们可以将其上传到GitHub中的一个沙箱文件夹，并在Slack或其他论坛中分享链接。

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

### 组合技能 你可能希望拥有相互依赖的技能。例如，你可能有一个文件上传技能用于上传文件，以及一个CSV生成技能用于生成CSV并上传。这种依赖管理尚未原生集成到市场或技能中，但你可以通过名称引用其他技能，如果它们已安装，模型会调用它们。

### 衡量技能 为了了解技能的表现，我们使用PreToolUse钩子来记录公司内的技能使用情况（代码示例在此）。这意味着我们可以找到那些受欢迎的技能，或者那些触发频率低于预期的技能。

### 开始 技能的最佳实践仍在演变。我们最好的技能大多始于几行代码和一个陷阱，然后随着Claude遇到新的边缘情况，人们不断添加内容而变得更好。

理解技能的最佳方式是开始动手，实验，并看看什么对你有用。

查看我们的技能文档 查找示例技能进行定制

本文由Thariq Shihipar撰写，他是Anthropic的技术人员，从事Claude Code的开发工作。