Created time
Apr 2, 2026 05:18 PM
category
library
date
Apr 3, 2026
status
Published
icon
password
slug
for-building-claude-code-how-we-use-skills
summary
构建 Claude Code 的经验教训主要探讨了如何有效地利用"技能"来加速开发，并总结了各种类型的技能及其最佳实践。
tags
Claude
工程实践
type
post
技能（Skills）已成为 Claude Code 中最常用的扩展方式之一。 它灵活、易于制作，分发也很方便。
在 Anthropic 内部，我们大量使用 Claude Code 的技能，目前有数百个技能正在活跃运转。以下是我们总结的关于如何借助技能加速开发的实战经验。
什么是技能？
如果你还不了解技能，建议先阅读官方文档，或观看关于 Agent 技能的课程。本文默认你已对技能有基本认识。
关于技能，有一个常见误解：它们"只是 Markdown 文件"。其实技能最有意思的地方恰恰不在于文本本身，而在于它是一个包含脚本、资源和数据的文件夹，Agent 可以主动发现、探索并操作其中的内容。
我们发现，Claude Code 中那些最有价值的技能，往往都巧妙地利用了这些配置选项和文件夹结构。
技能类型
1. 库与 API 参考
这类技能说明了如何正确使用某个库、CLI 或 SDK——既可以针对内部库，也可以针对 Claude Code 有时处理不好的常用库。通常包含参考代码片段文件夹，以及一份 Claude 在编写脚本时应避开的"坑点"清单。
示例：
billing-lib—— 内部计费库：边缘情况、易错点等
internal-platform-cli—— 内部 CLI 封装器的每个子命令及使用示例
frontend-design—— 帮助 Claude 更好地掌握你的设计系统
2. 产品验证
这类技能描述如何测试或验证代码是否正常工作，通常与 Playwright、tmux 等外部工具配合使用。
验证技能对于确保 Claude 的输出正确性非常有价值，值得让工程师花上一周时间把它做精。可以尝试让 Claude 录制输出视频，或在每一步执行程序化断言——这些通常通过在技能中内嵌各类脚本来实现。
示例：
checkout-verifier—— 用 Stripe 测试卡驱动结账 UI，验证发票状态
tmux-cli-driver—— 用于需要 TTY 的交互式 CLI 测试
3. 数据获取与分析
这类技能连接到你的数据和监控栈，可能包含带凭据的取数库、特定仪表板 ID，以及常见工作流的操作说明。
示例：
cohort-compare—— 对比两个群体的留存或转化，标记显著差异
grafana—— 数据源 UID、集群名称、问题与仪表板的对照表
4. 业务流程与团队自动化
这类技能将重复性工作流封装为一条命令。指令通常简洁，但可能依赖其他技能或 MCP。将结果保存在日志文件中，有助于模型保持一致性。
示例：
standup-post—— 汇总工单、GitHub 活动和 Slack 信息，生成日报
create-ticket—— 强制执行工单规范（有效值、必填项）及后续流程
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-service—— 构建、冒烟测试、灰度发布及回滚
cherry-pick-prod—— 自动执行 cherry-pick 和冲突解决
8. 运维手册（Runbooks）
这类技能接收症状输入（如 Slack 讨论、告警或错误特征），执行多工具调查，并生成结构化报告。
示例：
service-debugging—— 将症状映射到工具和查询模式
oncall-runner—— 获取告警、检查常见诱因并格式化结果
log-correlator—— 根据请求 ID 关联所有系统的日志
9. 基础设施运维
这类技能执行日常维护和操作程序，其中一些涉及破坏性操作，因此需要设置护栏。这让工程师在关键操作中更容易遵循最佳实践。
示例：
resource-orphans—— 查找孤儿资源，在 Slack 确认后清理
dependency-management—— 组织的依赖审批工作流
cost-investigation—— 调查存储或流量费用激增的原因
制作技能的技巧
确定好要做什么技能之后，该怎么写？以下是我们总结的一些最佳实践。
我们最近还发布了 Skill Creator，让在 Claude Code 中创建技能变得更简单。
不要陈述显而易见的事
Claude Code 对你的代码库了解很多，Claude 本身也精通编程。如果你的技能主要传递的是"知识"，请专注于那些能改变 Claude 常规思路的信息，而不是它本来就知道的东西。
frontend-design 技能是个好例子——它通过迭代，帮助 Claude 避开了像 Inter 字体、紫色渐变这类陈旧的设计套路。
建立"坑点"（Gotchas）部分
技能中信噪比最高的内容就是"坑点"部分。这些内容应该根据 Claude 在使用你的技能时遭遇的常见失败点来积累。理想情况下，你应该随着时间不断更新技能，把新发现的坑点补进去。
善用文件系统与渐进式披露
技能是一个文件夹，你应该把整个文件系统当作一种上下文工程和渐进式披露的手段。告诉 Claude 技能目录里有哪些文件，它会在合适的时候主动读取它们。
最简单的形式，是让 Claude 指向其他 Markdown 文件。比如，你可以把详细的函数签名和用法示例拆分到
references/api.md 中。又比如，如果最终输出是 Markdown 文件，你可以在 assets/ 目录下放一个模板供 Claude 直接复用。避免过度限制 Claude
Claude 通常会努力遵守你的指令。正因为技能是可复用的，你要注意不要把指令写得太死——给它需要的信息，但也给它适应具体情况的灵活空间。
考虑设置流程
某些技能可能需要用户先提供上下文。比如，做一个向 Slack 发送日报的技能，你可能希望 Claude 先询问发布到哪个频道。
一个好的模式是：将这些配置信息存储在技能目录下的
config.json 文件中。如果未设置，Agent 可以主动询问用户，也可以在指令中让 Claude 调用 AskUserQuestion 工具。描述字段是给模型看的，不是给人看的
Claude Code 启动会话时，会列出所有可用技能及其描述。Claude 通过扫描这些描述来判断"是否有技能能处理当前请求"。因此，描述字段不是摘要，而是触发条件说明——要写清楚"什么时候该用这个技能"。
记忆与数据存储
某些技能可以通过在内部存储数据来实现某种形式的"记忆"——可以是简单的文本日志、JSON 文件，也可以是完整的 SQLite 数据库。
举个例子：
standup-post 技能可以保留一份 standups.log。下次运行时，Claude 读取历史记录，就能知道自昨天以来发生了哪些变化。注意：技能目录中的数据在升级时可能被删除，因此应将其存储在稳定文件夹中。目前我们提供
${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定存储路径。给 Claude 提供脚本与生成代码
你能给 Claude 的最强工具之一就是代码本身。 提供现成的脚本和库，可以让 Claude 把精力集中在组合逻辑和决策上，而不是重复搭建样板代码。
比如，在数据科学技能中，你可以预先提供一组辅助函数；Claude 则可以即时生成脚本来组合这些函数，完成更高阶的分析任务。