Skills 是什么？Claude 官方教你做一个好用的 Skill

Claude Code 团队上周写了一篇文章，来报告他们在内部是怎样使用 Skills 的。借着他们这篇分享，我们来讲讲 Skill 是什么，以及怎样参考 Claude Code 团队的履向来打造我们本身的好用 Skill。
在 Claude Code 的 Skill 实践文章中，Skill 的界说比力靠近一个给 Agent 使用的任务履历包：把一类任务里反复用到的阐明、脚本、模板、设置和坑点，整理成一个可以被 Claude 发现和调用的文件夹。
而 Skills 也成了 Claude Code 最常用的扩展点之一。这不难明白，它创建起来不复杂、使用机动，在团队里分发也很方便。Anthropic 内部在用的 Skill 已经有数百个，现在来看看他们有什么最佳实践可以分享给我们。
Skills 不是一个 Markdown 文件

第一次看到 Skills，我们容易把它明白成一份提示词，或是一个 SKILL.md 文件。但 Skill 着实是一个文件夹，内里可以放 instructions、scripts、assets、data 等内容，Claude Code、Codex、OpenClaw、Hermes Agent 这类支持 Skills 的 Agent 工具，可以在实行任务时发现、读取和使用这些资源。
真实项目中的大多数履历，我们着实很难靠一段提示词说清楚。某个内部 CLI 有哪些子下令，某个付出流程要怎么验证，某张表哪个字段才是标准 user_id，CI 挂了以后应该先看那里，生产情况干系利用有哪些限定。这些东西每每分散在文档、代码、群聊和多个人的影象中，人类工程师大概知道这东西是怎么样运作的，但 Agent 每次干活就要重新猜了。
Skills 能把这些分散的履历收拢到一个明白的地方。一旦 Agent 遇到类似任务，就可以先看这个 Skill 中的阐明文件，再按内里的脚本、模板和排查步调去实行。它的作用不是让 prompt 写得更美丽，而是让 Agent 少猜一点，多复用一点已经沉淀下来的项目履历。

图注：Skill 不是单个 Markdown 文件，而是一个可以包罗文档、脚本、模板和资源的文件夹
Claude 内部的 9 类 Skill

Claude Code 团队梳理了内部的 Skills，发现它们大抵可以分成 9 类。固然，这不是一个终极标准，但是很得当用来明白 Skills 可以放什么内容。

第一类是库和 API 参考。像是 Claude 内部的 billing library 有哪些界限情况、内部 CLI 支持哪些子下令、某个 SDK 应该怎么正确调用。
这类 Skill 紧张办理的是“Claude 知道怎么写代码，但不知道你们这个库有什么特殊用法”的标题。很多团队内部工具都有本身的约定和汗青包袱，如果不提前写清楚，Agent 很容易按照通用履历去猜，末了写出看似公道但现实不能用的代码。
第二类是产物验证。这类 Skill 会告诉 Claude 怎么确认功能真的跑通了，像是用 Playwright 跑完备注册流程，用 Stripe 测试卡验证 checkout 状态，或是用 tmux 测试那些须要真实终端情况的交互式 CLI。
它的重点是让 Agent 不要停在“代码写完了”，而是继续走到“功能真的验证过了”。验证类 Skills 对 Claude 内部输出质量的提拔是最显着的，以致值得让工程师专门花时间把它做好。
第三类是数据分析，这类 Skill 会告诉 Claude 怎样毗连数据堆栈、监控体系、Grafana、Datadog，也会阐明哪些表能查、字段怎么对应、dashboard 在那里。
这类 Skill 得当沉淀团队里的数据口径，克制 Agent 查错表、看错字段，大概把差别体系里的指标混在一起表明。
第四类是业务流程和团队自动化，像是天生例会、创建 ticket、整理每周回首。它办理的是那些重复出现、格式相对固定，但每次又须要联合上下文整理的信息流任务。
第五类是代码脚手架和模板，像是创建新服务、新迁徙、新内部应用，把认证、日记、摆设设置这些固定内容提前接好。如许 Claude 创建新项目时，就不消从零开始猜团队的工程布局。
第六类是代码质量和 review，代码风格、测试规范，大概让一个新的 subagent 做代码查察。这类 Skill 可以把团队在 code review 里反复夸大的规则，变成 Agent 实行任务时会自动参考的查抄项。
第七类是 CI/CD 和摆设，盯 PR、重试偶发失败的 CI、办理归并辩论、跟进灰度发布和回滚，都属于这一类。它更方向把开发流程里的后半段交给 Agent 跟进，尤其得当那些步调明白、但人工盯起来很耗时间的任务。
第八类是故障处置处罚，也就是把报警、Slack 线程、错误日记等标题征象，转成一套可排查的流程。先查哪个 dashboard，再看哪类日记，末了按什么格式输出结论。它的代价在于镌汰临场排查时的杂乱，让 Agent 按既定次序推进。
第九类是根本办法运维，像是整理孤立资源、依靠管理、本钱排查，以及一些须要掩护规则的高风险利用。这类 Skill 尤其须要把界限写清楚，哪些下令可以自动实行，哪些利用必须先让人确认，都应该提前放进阐明里。
避坑指南

Anthropic 在文章里提到，写 Skill 时不要重复 Claude 原来就知道的内容。像是“代码要可读”“测试要覆盖关键路径”“注意错误处置处罚”这类要求，Claude 默认也知道，把它们写进 Skill 里，只会占用上下文。
对于项目而言，真正有代价的是当中的特殊情况，也就是 gotchas。
像是 subscriptions 表是 append-only，查订阅状态时要取 version 最高的那一行，而不是近来创建的那一行；API gateway 里叫 @request_id，billing service 里叫 trace_id，但它们着实指向同一个值；staging 返回 200，不代表 Stripe webhook 真的处置处罚乐成，还要去 payment_events 查真实状态…
这些内容看起来很噜苏，但正是 Agent 最容易踩坑的地方。一个好的 Skill 不肯定一开始就很复杂，它可以先从几行阐明和一个坑点开始。之后每次 Claude 做错了，就把新的履历补进去。如许 Skill 会徐徐从“提示 Claude 做什么”，变成“记载 Claude 在这个项目里曾经错过什么”。
文件布局是上下文

这里尚有一个很实用的 Skill 写法：不要把全部东西都塞进 SKILL.md，可以把文件体系本身当成一种渐进式上下文。SKILL.md 只负责告诉 Claude 这个 Skill 得当什么场景，以及差别情况应该去读哪些文件。
举个例子，你可以把具体的 API 署名放到 references/api.md，输出模板放到 assets/，排查待办 job 的方法单独放到 stuck-jobs.md。Claude 不消一开始就读取全部内容，只要在任务须要时再去看对应文件就够了。
这和 Agent 的工作方式很匹配。你给 Agent 一整本手册，它大概会抓不住重点。但你告诉它“遇到 A 情况去看 A 文件，遇到 B 情况去看 B 文件”，它就会按需使用上下文了。
写给模子看的 description

Skill 尚有一个容易被忽略的细节：description 不是写给人看的阐明，而是写给 Claude 判定“什么时间应该调用这个 Skill”的触发条件。
Claude Code 启动 session 时，会构建一份可用 Skills 列表，并扫描每个 Skill 的 description，判定当前哀求是否匹配。description 是一个触发阐明，而不是一句产物先容。
一个负责盯 PR 的 Skill，description 里最好出现 “babysit PR”“monitor CI”“retry flaky tests” 这类具体触发词。如许用户说“帮我盯一下这个 PR”时，Claude 更容易想起它。如果 description 写成“这个 Skill 可以进步开发服从”，模子反而很难判定什么时间该用。

图注：官方给出的示例
带影象的 Skill

有些 Skill 还可以生存汗青记载。
官方举了一个 standup-post 的例子：它可以把每次天生过的站会存到 standups.log，下次再运行时，Claude 就能读取之前的记载，知道本日和昨天相比发生了什么变革。
这个计划很淳厚，但有效。很多团队开会流程之一，是要和上一次的例会举行对比，看看这次新增了什么、这个 PR 前次卡在那里、昨天的报警有没有重复出现、本周和上周相比有哪些变革。把这些汗青结果存在 Skill 里，Agent 实行同类任务时就能得到一点汗青记载，保持集会的连续性。
固然，这里的“影象”不消明白得太复杂。它可以只是一个 append-only 文本日记、JSON 文件，也可以是 SQLite 数据库。重点是让 Skill 不但生存规则，也能生存这个任务已往实行过的结果。
团队怎样分发 Skill

在分发方式上，Anthropic 提到两种常见路径。第一种是直接把 Skills 放进代码堆栈，比如 ./.claude/skills，这得当小团队大概项目数量不多的情况。第二种是做成 plugin，通过内部 marketplace 分发。团队规模变大后，每个人不肯定须要安装全部 Skills，marketplace 可以让各人按需安装，也方便做设置流程。
Anthropic 内部的做法也比力轻。他们没有一个中心团队专门决定哪些 Skills 能进 marketplace，而是先让各人把 Skill 放到 GitHub 的 sandbox 目次，再通过 Slack 等渠道让别人试用。等它真的有人用、有代价，再通过 PR 移到 marketplace。
这很有参考性。Skills 原来就是从具体任务里长出来的，不须要一开始就计划成大而全的规范。先办理一个小标题，真的有人用，再徐徐补坑点、补脚本、补模板，反而更符合它的使用方式。
小结

Skills 可以明白成 Claude Code 给 Agent 准备的任务履历包。它把一类任务里反复出现的阐明、脚本、模板、设置、坑点和汗青记载放在一起，让 Claude 下次遇到类似任务时，可以直接复用已有履历。
我们要创建本身的 Skill 时，可以先从很小的 Skill 开始，把 Claude 经常写错的项目规则、常用脚本、输出模板和测试方式放进去。对团队来说，Skills 更像一种轻量的履历分发方式：工程师不消每次都手把手提示 Agent，踩过的坑也可以徐徐沉淀下来，成为下一次任务的一部门。
参考资料

Anthropic Blog《Lessons from building Claude Code: How we use skills》