深度干货！Anthropic 罕见公开内部文档，揭秘 Claude Code 技能玩法

• Anthropic 官方实战解析：Claude Code 技能九大分类、编写技巧与分发管理

• 深度干货｜Claude Code Skills 最佳实践：从分类设计到团队落地完整指南

• 拆解 Anthropic 内部用法：如何借助 Claude Code 技能体系实现研发提效

截至 2026 年 3 月，Anthropic 官方前端设计类技能安装量已突破 27.7 万次，其 Claude Code 技能生态自上线以来迎来爆发式增长，数千款技能覆盖开发全场景。

依托这套技能体系，Anthropic 研发效率实现跨越式提升：2026 年二季度，工程师日均代码产出达到 2024 年的 8 倍，超 80% 合并至生产库的代码均由 Claude 完成。

近期，Anthropic 首度公开内部实战报告，分享团队深度使用 Claude Code Skills 的一手经验。这份内容在全球开发者社区迅速走红，不少工程师评价：这不是普通教程，而是真正的内部落地方法论。

报告系统梳理了技能九大分类、核心编写要诀、文件结构设计、团队分发与效果衡量等全流程要点，尤其指出「坑点内容」「渐进式信息设计」是打造高价值技能的关键。

王吉伟频道翻译了这篇报告，完整还原 Anthropic 工程师的实战心得，帮大家从零搭建可落地、能提效的专属技能库。

PS：该报告英文原版内容以及文中提到的部分文档内容，公众号主页发消息260609，有需要的朋友自取。

以下是正文。

打造 Claude Code 的独家心得：我们是怎么玩转技能的 Lessons from building Claude Code: How we use skills

技能已经成为 Claude Code 里最高频使用的扩展方式。它灵活、易上手，分享传播也超方便。

但正因为太灵活，反而让很多人犯了选择困难症：什么类型的技能值得做？结构怎么设计才合理？又该在什么时机分享给团队？

我们在 Anthropic 内部把技能玩得相当深——目前在跑的已经有好几百个了。下面这些，就是我们用技能给开发工作加速时，踩坑总结出来的实战经验，拿走不谢！

技能到底是个啥？ What are skills?

技能本质上是一个文件夹，里面装着指令、脚本和各类资源，智能体可以自动发现并调用它们，从而更准确、更高效地完成任务。本文默认你已经懂技能的基础操作；如果你是新手，建议先去 Skilljar 上刷一遍我们的《智能体技能入门课程》。

我们最常听到一个误解：「技能不就是几个 Markdown 文件嘛。」——大错特错！技能是一个完整文件夹，里面可以有脚本、素材、数据等各种内容，智能体可以自主探索、发现和操作这些资源。

在 Claude Code 里，技能还能玩很多花活，包括注册动态钩子在内的丰富配置选项全都支持。

实测下来，那些最给力的技能，无一例外都把这些配置选项和文件夹结构用得明明白白。

技能的九大类别 Types of skills

把 Anthropic 内部所有技能盘了个遍之后，我们发现它们其实可以归为九大类。最好用的技能职责单一，稳稳落在某一类里；而那些想「一招鲜吃遍天」的技能，横跨好几个类别，反而把智能体整懵了。

这不是什么标准答案，但确实是个好用的框架，帮你找出自己技能库里的空白地带。

Claude Code 团队对内部技能进行了分类，发现可以划分为九个独立类别。

1. 库与 API 参考 Library and API reference

这类技能专门解释如何正确使用某个库、命令行工具或 SDK。不管是内部私有库，还是 Claude Code 有时候会用错的通用库，都能覆盖。这类技能通常会附带一个参考代码片段文件夹，外加一份「坑点避雷清单」。

典型案例：

• •billing-lib—— 内部计费库的边界情况、各种自伤型操作等防踩坑指南

• •internal-platform-cli—— 内部 CLI 封装工具的每一个子命令，附带使用时机示例

• •sandbox-proxy—— 配置公司开发环境出口网关：哪些主机可达、「连接被拒」怎么排查、白名单怎么加

这类技能告诉 Claude 怎么测试和验证代码是否正常运转，通常搭配 Playwright、tmux 或其他外部工具一起使用。

验证类技能对提升 Claude 输出质量的效果是九类里最立竿见影的，在内部有实打实的数据支撑。让一个工程师专门花一周时间把这类技能打磨好，绝对值回票价。

可以玩一些骚操作，比如让 Claude 录一段测试过程的视频方便复盘，或者在每一步强制做程序化断言来校验状态。这些通常通过在技能里内置一组脚本来实现。

典型案例：

• •signup-flow-driver—— 在无头浏览器里跑完整个「注册 → 邮件验证 → 新用户引导」流程，并在每一步插入状态断言钩子

• •checkout-verifier—— 用 Stripe 测试卡驱动结账 UI，验证发票是否正确落库

• •tmux-cli-driver—— 适用于需要 TTY 的交互式命令行测试场景

这类技能负责打通你的数据和监控体系。可以包含带认证信息的数据获取库、特定的仪表盘 ID，以及常见的数据获取操作指南。

典型案例：

• •funnel-query—— 「要看『注册→激活→付费』漏斗要 JOIN 哪些事件」，加上存有标准user_id的那张表到底在哪

• •cohort-compare—— 对比两个用户群的留存或转化，标记统计显著差异，附分群定义链接

• •grafana—— 数据源 UID、集群名称、「问题 → 仪表盘」对照表

• •datadog—— 字段参考（@request_idvstrace_id傻傻分不清？）、服务列表、指标前缀命名规范

这类技能把重复性工作流一键自动化。指令本身通常比较简单，但可能依赖其他技能或 MCP。对于这类技能，把历史执行结果存到日志文件里，能帮模型保持一致性，并回顾之前的执行情况。

典型案例：

• •standup-post—— 汇总任务追踪器、GitHub 动态和 Slack 历史记录 → 生成格式化站会内容，只展示增量变化

• •create- -ticket —— 强制校验工单字段（合法枚举值、必填项）+ 自动触发创建后工作流（通知负责人、Slack 关联链接）

• •weekly-recap—— 已合并 PR + 已关闭工单 + 部署记录 → 生成格式化周报

这类技能负责在代码库里生成特定功能的框架代码，可以和可组合的脚本配合使用。当脚手架包含一些纯代码无法完整表达的自然语言约束时，这类技能尤其好使。

典型案例：

• •new- -workflow —— 用你们的注解规范搭一个新的服务/工作流/处理器骨架

• •new-migration—— 数据库迁移文件模板 + 常见坑点清单

• •create-app—— 创建新内部应用，预置认证、日志和部署配置，开箱即用

这类技能在组织内部强制执行代码规范并协助做代码审查，可以引入确定性脚本或工具来保证最大健壮性。还可以配置成钩子自动触发，或集成进 GitHub Actions 流水线里跑。

• •adversarial-review—— 派一个「新眼睛」子智能体来挑毛病，修复问题后反复迭代，直到只剩鸡毛蒜皮的细节

• •code-style—— 强制执行代码风格，尤其是那些 Claude 默认做得不到位的地方

• •testing-practices—— 怎么写测试、测什么，一份完整指南

这类技能帮你在代码库里搞定代码获取、推送和部署，可能会引用其他技能来收集数据。

典型案例：

• •babysit-pr—— 监控 PR 状态 → 自动重跑不稳定的 CI → 解决合并冲突 → 启用自动合并，全程帮你盯着

• •deploy- —— 构建 → 冒烟测试 → 分批流量切换（同步对比错误率）→ 出现回归自动回滚

• •cherry-pick-prod—— 独立工作区 → cherry-pick → 处理冲突 → 按模板创建 PR

这类技能接收一个异常信号（Slack 消息、告警或报错特征），然后拉通多个工具进行排查，最终输出一份结构化的排查报告。

典型案例：

• • -debugging —— 针对最高流量服务，建立「症状 → 工具 → 查询模式」的完整映射

• •oncall-runner—— 拉取告警 → 排查常见嫌疑点 → 格式化输出排查结论

• •log-correlator—— 给定一个请求 ID，从所有可能经手该请求的系统里捞出相关日志

这类技能负责执行日常维护和运维操作，其中部分操作有破坏性，因此加了安全护栏。让工程师在执行关键操作时更容易遵守最佳实践，不容易手滑出事。

典型案例：

• • -orphans —— 找出孤立的 Pod/存储卷 → 发到 Slack → 静默观察期 → 用户确认 → 级联清理

• •dependency-management—— 组织内的依赖审批工作流

• •cost-investigation—— 「为什么我们的存储/出口流量费用突然飙了」，附带具体存储桶和查询模式

确定要做什么技能之后，怎么写才最给力？这些是 Claude Code 团队压箱底的最佳实践和独家技巧，全部奉上！

废话少说，别跟 Claude 讲它早就知道的事 Don’t state the obvious

Claude 本来就会写代码，也能读懂你的代码库。一个技能如果只是在重复 Claude 默认就会做的事，那就是白白占用上下文，没有任何增量价值。如果你做的技能主要是在传递知识，那就专注于那些能打破 Claude 思维定式的信息。

前端设计技能(https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) 就是个绝佳示范，它是 Anthropic 的一位工程师与用户反复打磨出来的，专门改善 Claude 的设计审美，避免它总是套用 Inter 字体和紫色渐变这类老套模式。

坑点专区是灵魂，一定要好好建 Build a gotchas section

技能里含金量最高的内容，就是**「坑点」（Gotchas）**这一块。这个专区应该从 Claude 在使用你的技能时真实踩过的坑里提炼出来，并随着时间不断迭代更新。

举几个实际例子：

"subscriptions 表是只增不改的。你要的那条记录是 version 最大的那行，不是 created_at 最新的那行。"

"这个字段在 API 网关里叫 @request_id，在计费服务里叫 trace_id，其实是同一个值，别被名字骗了。"

"Staging 环境即使 Stripe webhook 没有真正处理，也会返回 200。想看真实状态，去查 payment_events 表。"

SKILL.md 文件指向多个其他文件，Claude 可以在特定场景下按需引用。比如，如果某个任务处于 pending 状态，它应该去读 stuck-jobs.md。

前面说了，技能是一个文件夹，不只是一个 Markdown 文件。你应该把整个文件系统看作上下文工程和渐进式信息披露的舞台——告诉 Claude 技能里有哪些文件，它就会在合适的时机主动去读对应的文件。

最简单的渐进式信息披露玩法，就是在主文件里指向其他 Markdown 文件，让 Claude 按需查阅。比如，你可以把详细的函数签名和用法示例拆分到references/api.md里。

再比如：如果你的最终输出是一个 Markdown 文件，可以在assets/目录下放一个模板文件供 Claude 直接复用。

参考资料文件夹、脚本文件夹、示例文件夹等等，通通可以有，帮 Claude 把活干得更漂亮。

别把 Claude 框死，给它留点发挥空间 Avoid railroading Claude

Claude 会尽力遵守你的指令，而且技能要被反复复用，所以指令太过具体反而会出问题。给 Claude 它需要的信息就好，但别把每一步都规定死，让它有足够的弹性根据实际情况自主应对。

举个例子：

好好设计初始化流程，别让用户一头雾水 Think through the setup

上图中的技能会在 Slack 频道未配置时主动询问用户。

有些技能需要先向用户收集一些上下文配置。比如，如果你做的是一个自动把站会发到 Slack 的技能，就得先让 Claude 问清楚：发到哪个频道？

一个好用的模式：把这些初始化信息存在技能目录下的config.json文件里，就像上面的例子那样。如果配置还没建立，智能体就会主动向用户询问所需信息。

如果你想让智能体呈现结构化的多选题交互，可以指示 Claude 调用AskUserQuestion工具。

description字段是写给模型看的，不是写给人看的 Write descriptions for the model, not for humans

Claude Code 每次启动会话，都会扫描所有可用技能及其描述，生成一份清单。正是这份清单决定了 Claude 会不会判断「这个请求有对应的技能可用」。所以，description字段不是摘要，而是「什么情况下该触发这个技能」的触发条件说明。

*在技能描述里加上触发关键词，比如「babysit」，会非常有帮助。

给 Claude 装上「记忆」，让它越用越聪明 Help Claude remember

这个文本日志文件帮助 Claude 记住过去发生的事，比如审查了 Sarah 的认证 PR。

有些技能可以通过在内部存储数据来实现一定程度的「记忆」功能。存储方式可以简单到只增不改的文本日志或 JSON 文件，也可以复杂到一个 SQLite 数据库。

举个例子：一个standup-post技能可以维护一份standups.log，记录它写过的每一条站会内容。下次运行时，Claude 会读取自己的历史记录，清楚地知道昨天以来发生了哪些变化。

可以使用环境变量${CLAUDE_PLUGIN_DATA}获取一个稳定的数据存储目录，更多关于技能数据持久化的内容请看这里：https://code.claude.com/docs/en/plugins-reference-data-directory

提前备好脚本，让 Claude 直接上手组合 Store scripts and generate code

给 Claude 提供现成的代码，是你能给它的最强武器之一。有了脚本和函数库，Claude 就能把注意力放在「编排组合」上——思考下一步该怎么做，而不是费劲从零重写样板代码。

比如，在你的data-science技能里，可以放一个函数库，专门从事件数据源里拉取数据。为了让 Claude 能做复杂分析，给它配一套这样的辅助函数：

这样，Claude 接到「周二发生了什么？」这类问题时，就能即时生成脚本，把这些函数组合起来做更深入的分析：

按需触发的钩子，该用就用 Use on-demand hooks

技能可以包含只在被调用时才激活、且只在本次会话期间生效的钩子。对于那些平时不想一直挂着、但关键时刻超级顶用的功能，这种方式再合适不过了。

几个例子：

• •/careful—— 通过 PreToolUse 钩子在 Bash 中拦截rm -rf、DROP TABLE、强制推送、kubectl delete。只有在你明确知道自己要动生产环境时才需要开——要是一直挂着，你早晚会被逼疯的。

• •/freeze—— 阻止对特定目录以外任何文件的编辑/写入。调试时神器一枚：「我只想加几条日志，但我老是顺手把不相关的代码也改了。」

技能最大的好处之一，就是可以在团队里共享传播。

分享方式主要有两种：

• • 把技能提交到代码仓库里（放在./.claude/skills目录下）

• • 打包成插件，上传到 Claude Code 插件市场，让团队成员自行安装（详见[官方文档]：https://code.claude.com/docs/en/plugin-marketplaces

对于规模小、跨仓库不多的团队，直接提交到仓库里完全够用。

但需要注意：每多一个提交的技能，模型上下文就会多一点点负担。随着团队规模增长，内部插件市场能让你更灵活地分发技能，团队成员自己决定装哪些，还能配套设计安装引导流程。

怎么管理技能市场 Managing a skills marketplace

哪些技能能上市场？怎么让大家来提交？

在 Anthropic，我们没有专门的中心化决策团队，而是靠「真正有用的东西自然会浮出水面」这个理念驱动。如果有人做了个想让大家试试的技能，可以传到 GitHub 的沙盒目录里，然后在 Slack 或其他渠道里扔个链接。

一旦某个技能积累了一定的使用量（由技能作者自己判断），就可以提一个 PR，把它正式迁入市场。

技能之间可以互相组合 Composing skills

你可能想让技能之间互相依赖。比如，你有一个上传文件的技能，还有一个生成 CSV 并上传的技能。目前，市场和技能系统原生还不支持依赖管理，但你可以直接在技能里按名称引用其他技能——只要目标技能已安装，模型就会自动调用它，完全不用额外配置。

怎么衡量技能的实际效果 Measuring skills

想知道技能用得怎么样，我们用了一个 PreToolUse 钩子，在公司内部记录技能的调用日志。

示例代码如下：

measure-skills.bash

  echo "$(date -u +%s)  $USER   $skill  $args" >> ~/.claude/skill-usage.

这样就能找出哪些技能超受欢迎，哪些触发率比预期低，精准定位改进点。

行动起来！别光看不练 Get started

技能的最佳实践还在持续进化中。我们内部最好的那些技能，一开始往往只有几行代码和一个坑点，然后随着 Claude 踩到新的边界情况，大家不断往里加料，慢慢变成了精品。

理解技能最好的方式就是直接上手，大胆试错，找到最适合你的玩法。

• • 查看技能官方文档：https://code.claude.com/docs/en/skills

• • 找示例技能来改造定制：https://github.com/anthropics/skills

全文完

王吉伟频道图书《一本书讲透Agentic AI》已出版，完整构建Agentic AI在企业应用中的全景式知识体系，内容跨越 “基础认知-技术原理-业务应用-组织战略-实操指南” 五大板块，为读者提供从认知共识、技术解构、业务对接到组织变革的端到端路线图，欢迎大家关注。

【赠书福利进行中】

感谢大家的长期关注与支持。欢迎小伙伴们在文末留言与转发，王吉伟频道会随机选取读者，《一本书讲透Agentic AI》包邮到家。

【 文末福利1 】：后台发消息研报2026，获取15篇 2026年 AI Agent研报 。

【文末福利2】： 后台发消息Workflow，获取 Agentic Workflow 相关25篇论文。

【文末福利3】：后 台发消息agentic，获取Agentic AI相关资源 。

【文末福利4】：后台发消息RPA Agent，获取 相关论文和研报。

1、

2、

3、

4、

5、

6、

7、

8、

8、

10、