Thariq 2026-03-23 09:02 福建
Anthropic团队基于内部数百个技能的实战经验
前言
Anthropic 团队基于内部数百个技能的实战经验，梳理了 Claude Code 技能的九大类型，涵盖 API 参考、产品验证、代码脚手架与 CI/CD 部署等方向，并分享了编写高质量技能的核心技巧与团队分发最佳实践。
今日前端早读课文章由 @Thariq 分享，@飘飘编译。
译文从这开始～～
技能已成为 Claude Code 中最常用的扩展方式之一。它灵活、易于创建，也便于分发。
但这种灵活性也让人难以知晓哪种方式效果最佳。哪些技能值得去打造？写出优质技能的秘诀是什么？何时与他人分享这些技能？
我们在 Anthropic 内部大量使用 Claude Code 的技能功能，目前已有数百个技能在日常工作中活跃运行。以下是我们在用技能加速开发过程中总结出的经验。 【第3670期】AI 工程实战：Claude Code 团队总结的六条反直觉缓存法则
#### 什么是技能？
如果你刚接触技能，建议先阅读我们的文档，或观看我们在 Skilljar 上最新发布的「智能体技能」课程。本文假设你已经对技能有了一定的了解。
关于技能，我们经常听到一个误解：技能 "不过是 Markdown 文件"。然而，技能最有趣的地方恰恰在于 —— 它们远不只是文本文件。技能本质上是文件夹，里面可以包含脚本、资源文件、数据等内容，供智能体自主发现、探索和操作。
在 Claude Code 中，技能还提供了丰富的配置选项，包括注册动态钩子（hooks）。
我们发现，最出色的那些技能往往巧妙地运用了这些配置选项和文件夹结构。 【第3664期】Claude Code 系统化方法：从规划到高效交付
#### 技能的类型
在对我们所有的技能进行梳理归类后，我们注意到它们大致可以归为几个反复出现的类别。最出色的技能能清晰地归入其中一类；而令人困惑的技能往往横跨多个类别。这不是一份详尽无遗的清单，但可以帮你审视一下，在你的团队中是否还缺少某些类型的技能。
##### 1. 库与 API 参考
这类技能用于说明如何正确使用某个库、命令行工具或 SDK，既可以针对内部库，也可以针对 Claude Code 有时会出错的常见库。这类技能通常包含一个参考代码片段文件夹，以及一份 Claude 在编写脚本时需要避免的 "坑" 的清单。 示例：
* billing-lib —— 你的内部计费库：边界情况、易踩的坑等
* internal-platform-cli —— 内部 CLI 封装工具的每个子命令及其使用场景示例
* frontend-design —— 让 Claude 更好地适配你的设计系统
##### 2. 产品验证
这类技能描述了如何测试或验证你的代码是否正常运行，通常搭配 Playwright、tmux 等外部工具来执行验证。 【第3662期】快速上手 Claude 技能：从零到可用
验证类技能对于确保 Claude 输出的正确性极为重要。值得专门安排一位工程师花上一周时间，把验证技能打磨到极致。
可以考虑采用一些技术手段：让 Claude 录制一段输出过程的视频，以便你能直观看到它到底测试了什么；或者在每个步骤强制执行程序化的状态断言。这些做法通常通过在技能中放入各种脚本来实现。 示例：
* signup-flow-driver —— 在无头浏览器中跑通注册→邮箱验证→引导流程，并在每个步骤设置状态断言钩子
* checkout-verifier —— 使用 Stripe 测试卡驱动结账界面，验证发票是否确实进入了正确的状态
* tmux-cli-driver —— 用于需要 TTY 的交互式命令行测试场景
##### 3. 数据获取与分析
这类技能用于连接你的数据和监控体系。可能包含带有凭证的数据拉取库、特定的仪表盘 ID 等，以及关于常见工作流或数据获取方式的说明。 示例：
* funnel-query —— "要查看注册→激活→付费的漏斗，需要关联哪些事件？"，以及存放规范化 user_id 的实际数据表
* cohort-compare —— 对比两个用户群的留存或转化率，标记统计上显著的差异，并关联到分群定义
* grafana —— 数据源 UID、集群名称、问题→仪表盘的对照表
##### 4. 业务流程与团队自动化
这类技能将重复性的工作流自动化为一条命令。通常是较为简单的指令说明，但可能会涉及对其他技能或 MCP 的复杂依赖。对于这类技能，将历次执行结果保存在日志文件中，有助于模型保持一致性并回顾之前的执行情况。 【早阅】在 AI 时代避免技能退化 示例：
* standup-post —— 汇总你的任务跟踪器、GitHub 动态和之前的 Slack 消息，生成格式化的站会报告，只展示增量变化
* create-<工单系统>-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 —— "为什么我们的存储 / 出口带宽费用突然飙升"，附带具体的存储桶和查询模式
#### 编写技能的实用建议
确定了要做的技能之后，该怎么写？以下是我们总结出的一些最佳实践、技巧和窍门。
我们最近还发布了技能创建器（Skill Creator），让你在 Claude Code 中创建技能更加便捷。
##### 1、不要赘述显而易见的事
Claude Code 对你的代码库已经有很深的了解，Claude 本身对编程也非常精通，包括许多默认的编程理念。如果你发布的技能主要是关于知识传递的，请着重于那些能打破 Claude 惯性思维的信息。
前端设计技能就是一个很好的例子 —— 它由 Anthropic 的一位工程师在与客户反复迭代中打造而成，旨在提升 Claude 的设计品味，让它避开诸如 Inter 字体和紫色渐变之类的 "经典套路"。 【早说】编程智能体如何重塑工程、产品与设计
##### 2、建立一个 "踩坑指南"
##### !Image 4: 图像
在任何技能中，信息密度最高的内容就是 "踩坑指南"（Gotchas）部分。这个部分应该从 Claude 使用你的技能时反复遇到的常见失败点中提炼而来。理想情况下，你应该随着时间推移不断更新技能，持续收录这些坑。
##### 3、善用文件系统与渐进式信息披露
正如前面所说，技能是一个文件夹，而不仅仅是一个 Markdown 文件。你应该把整个文件系统视为上下文工程和渐进式信息披露的载体。告诉 Claude 你的技能里有哪些文件，它会在合适的时机去读取它们。
渐进式信息披露最简单的形式，就是指引 Claude 去查阅其他 Markdown 文件。例如，你可以将详细的函数签名和用法示例拆分到references/api.md中。
另一个例子：如果你最终输出的是一个 Markdown 文件，可以在assets/目录下放一个模板文件，供复制和使用。
你可以建立参考资料、脚本、示例等文件夹，帮助 Claude 更高效地工作。
##### 4、避免把 Claude "框死"
Claude 通常会尽力遵循你的指令，而技能又是高度可复用的，因此你需要警惕指令写得过于具体。给 Claude 提供它需要的信息，但也要留出足够的灵活性，让它能随机应变。
##### 5、周全考虑初始化环节
有些技能可能需要用户提供上下文信息来完成初始化。例如，如果你做了一个将站会内容发到 Slack 的技能，你可能希望 Claude 先询问用户要发到哪个 Slack 频道。
一个好的做法是将这些配置信息存储在技能目录下的config.json文件中（如上例所示）。如果配置尚未设定，智能体就会主动询问用户。
如果你希望智能体以结构化的多选题形式向用户提问，可以指示 Claude 使用AskUserQuestion工具。
##### 6、描述字段是写给模型看的
当 Claude Code 启动一个会话时，它会构建一份所有可用技能及其描述的清单。Claude 正是通过扫描这份清单来判断 "这个请求是否有对应的技能可用？"。这意味着，描述字段不是一段摘要 —— 而是对何时触发这个技能的说明。
##### 7、记忆与数据存储
有些技能可以通过在自身内部存储数据来实现一种 "记忆" 机制。你可以用最简单的方式来存储数据，比如一个只追加的文本日志文件或 JSON 文件，也可以复杂到用一个 SQLite 数据库。
例如，一个 standup-post 技能可以维护一份standups.log，记录每次发出的内容。这样下次运行时，Claude 就能读取自己的历史记录，清楚地知道从昨天到现在有什么变化。
存储在技能目录中的数据可能会在技能升级时被删除，因此你应该将数据保存在一个稳定的目录中。目前我们为每个插件提供了${CLAUDE_PLUGIN_DATA}作为稳定的数据存储路径。
##### 8、存放脚本与生成代码
你能给 Claude 的最强大武器之一就是代码。为 Claude 提供脚本和函数库，它就能把精力花在组合编排上 —— 思考下一步该做什么，而不是反复重写样板代码。
例如，在你的数据科学技能中，你可以提供一组从事件源拉取数据的函数库。为了让 Claude 能做复杂分析，你可以给它一套辅助函数。
Claude 随后可以即时生成脚本，组合这些功能来完成更高级的分析 —— 比如回答 "周二发生了什么？" 这样的问题。
##### 9、按需钩子
技能可以包含仅在该技能被调用时才激活的钩子，且有效期持续到会话结束。适合用于那些你不想一直运行、但在特定场景下极为有用的强约束型钩子。
例如：
* /careful
—— 通过 PreToolUse 匹配器拦截 Bash 中的rm -rf、DROP TABLE、force-push、kubectl delete等操作。只有在你明确知道自己在操作生产环境时才需要开启 —— 要是一直开着，非把人逼疯不可。
* /freeze
—— 禁止对指定目录之外的文件进行任何编辑或写入。
在调试时特别好用："我只想加几行日志，但总是一不小心就 ' 顺手修了 ' 不相干的东西。"
#### 分发技能
技能最大的好处之一，就是你可以把它分享给团队的其他成员。
分享技能有两种方式：
* 将技能提交到代码仓库中（放在./.claude/skills目录下）
* 制作成插件，并通过 Claude Code 插件市场供用户上传和安装
对于规模较小、涉及仓库不多的团队，将技能直接提交到仓库中就很好用。但每一个提交进去的技能都会给模型的上下文增加一点负担。随着规模扩大，搭建一个内部插件市场可以让你更好地分发技能，同时让团队成员自行决定安装哪些。
##### 管理插件市场
如何决定哪些技能可以上架市场？大家又该怎么提交？ 【第3165期】谈谈如何设计一个插件（Plugin）体系
我们并没有一个集中的团队来做决策，而是让最有用的技能自然涌现出来。如果你有一个想让大家试试的技能，可以先上传到 GitHub 的沙盒文件夹中，然后在 Slack 或其他论坛里分享给大家。
一旦某个技能获得了足够的关注（由技能作者自行判断），作者就可以提交 PR，将其正式迁入市场。
这里需要提醒一句：创建劣质或冗余的技能实在太容易了，因此在正式发布之前，务必确保有某种审核筛选机制。
##### 技能的组合
你可能希望技能之间可以相互依赖。例如，你可能有一个文件上传技能负责上传文件，还有一个 CSV 生成技能负责生成 CSV 并上传。这种依赖管理目前在市场或技能体系中尚未原生支持，但你可以直接按名称引用其他技能，只要对方已安装，模型就会自动调用它们。
##### 衡量技能效果
为了了解技能的使用情况，我们使用了一个 PreToolUse 钩子，在公司范围内记录技能的调用日志（示例代码见此处）。这样我们就能发现哪些技能广受欢迎，哪些技能的触发频率低于预期。
#### 结语
技能是智能体手中极其强大而灵活的工具，但一切仍在早期阶段，我们都还在摸索最佳的使用方式。
与其说这是一份权威指南，不如把它看作我们在实践中验证过的实用经验合集。理解技能最好的方式就是动手去做、大胆试验，看看什么对你有效。我们的大多数技能最初不过是寥寥几行文字加一条踩坑提示，后来之所以越来越完善，是因为大家在 Claude 遇到新的边界情况时不断往里添砖加瓦。
希望这篇文章对你有所帮助，如有任何问题，欢迎随时交流。
关于本文
译者：@飘飘
作者：@Thariq
原文：https://x.com/trq212/status/2033949937936085378
这期前端早读课
对你有帮助，帮”赞“一下，