Claude Code 实践经验:Skills 的用法与设计心得
今天这篇文章,推荐给所有正在关注 Claude Code、也想把 Agent 工作流做深的人。作者 Thariq Shihipar(@trq212)目前在 Anthropic 参与 Claude Code 相关工作,本身就是一线建设者。这篇文章谈的,也不是抽象理念,而是他们在内部把 Skills 真正用起来之后沉淀出的经验。
按照作者的说法,Anthropic 内部已经有数百个 Skills 在活跃使用,所以你会发现,文中讲的不是“Skill 是什么”这种入门问题,而是更重要的几件事:Skills 应该怎么分类、怎么写得更稳、怎么在团队里分发,以及怎么避免它们越做越乱。对于已经开始接触 Agent 工程的人来说,这类一手经验,往往比单纯的产品文档更有价值。
以下是全文翻译,原始文章链接(https://x.com/trq212/status/2033949937936085378),Happy Reading!
Skills 已成为 Claude Code 中使用最广泛的扩展之一,其足够灵活,制作门槛低,便于分发。
但也正因这种灵活性,人们反而很难判断,到底什么样的 skill 值得做?写好一个 skill 的诀窍是什么,又该在什么时机把它分享给别人?
在 Anthropic 内部,我们已经在 Claude Code 中大规模使用 skills,目前有数百个skill 处于活跃使用状态。以下是我们在用 skills 加速开发过程中总结出的经验。
什么是 Skills?
如你刚接触 skills,我建议先阅读我们的 docs,或者观看我们最新的 Agent Skills Skilljar 课程;本文默认你已经对 skills 有一定了解。
经常听到一种误解:有人认为 skills “不过是 markdown 文件”。
实际上,skills 最有意思的地方恰在于,它们不只是文本文件。它们是一个文件夹,里面可以包含 scripts、assets、data 等等,而 agent 可以发现、浏览并操作这些内容。
在 Claude Code 中,skills 还支持大量 configuration options,包括注册动态 hooks。
我们发现,Claude Code 中一些最有意思的 skill,正是创造性地利用了这些 configuration options 与文件夹结构。
Skills 的类型
在梳理内部所有 skills 后,我们发现它们大致会聚集到几个反复出现的类别中。最好的 skill 往往能够清晰归入某一个类别;而那些让人困惑的 skill,通常是横跨了多个类别。这不是一份穷尽式清单,但它很适合作为一个思考框架,帮助你判断自己的组织里是否缺少某些类型的 skill。
1-库与 API 参考
这类 skill 用来说明:如何正确使用某个库、CLI 或 SDK。它既可以面向内部库,也可以面向那些 Claude Code 偶尔掌握得不够稳妥的常见库。这类 skill 往往会附带一个参考代码片段目录,以及一份“易踩坑事项(gotchas)”清单,帮助 Claude 在编写脚本时避开常见错误。
示例:
• billing-lib—— 你的内部计费库:包括边界情况、隐蔽坑点等• internal-platform-cli—— 你的内部 CLI 封装器的全部子命令,以及各自适用场景的示例• frontend-design—— 帮助 Claude 更好地遵循你的设计系统(design system)
2-产品验证
这类 skill 用来描述:如何测试或验证你的代码是否真的正常工作。它们通常会与外部工具搭配使用,比如 Playwright、tmux 等,以完成验证过程。
验证类 skill 对于确保 Claude 的输出正确,价值极高。很多时候,专门让一位工程师花上一周时间,把验证类 skill 打磨到足够优秀,是非常值得的。
你可以考虑采用这样的技巧:让 Claude 录下它输出过程的视频,这样你就能准确看到它究竟测试了什么;或者在每一步都加入可程序化检查的状态断言(assertions)。这类能力通常通过在 skill 中加入多种脚本来实现。
示例:
• signup-flow-driver—— 在无头浏览器(headless browser)中完整跑通“注册 → 邮箱验证 → 新手引导”流程,并在每一步提供状态断言 hooks• checkout-verifier—— 使用 Stripe 测试卡驱动结账界面,并验证 invoice 是否真的进入了正确状态• tmux-cli-driver—— 用于交互式 CLI 测试,适合那些被验证对象必须运行在 TTY 环境中的场景
3-数据获取与分析
这类 skill 负责连接你的数据体系与监控体系。它们可能包含用于携带凭证获取数据的库、特定 dashboard 的 id,以及常见工作流说明或获取数据的标准方法。
示例:
• funnel-query—— 说明“若要查看 signup → activation → paid,需要关联哪些事件”,以及真正保存规范user_id的那张表• cohort-compare—— 比较两个 cohort 的留存或转化,标出具有统计显著性的差异,并链接到对应的 segment 定义• grafana—— 提供数据源 UID、集群名称,以及“问题 → dashboard”的查询映射表
4-业务流程与团队自动化
这类 skill 会把重复性的工作流自动化为一条命令。它们通常只是相对简单的指令集合,但有时也可能依赖其他 skills 或 MCP。对于这一类 skill,把之前执行的结果保存到日志文件中,往往能帮助模型保持前后一致,并回顾这个工作流过去是如何执行的。
示例:
• standup-post—— 汇总你的工单跟踪器、GitHub 活动以及此前的 Slack 内容,生成格式化的 standup,只输出增量变化• create-<ticket-system>-ticket—— 强制执行 schema 约束(如合法枚举值、必填字段),并完成建单后的后续流程(提醒 reviewer、把链接贴到 Slack)• weekly-recap—— 将已合并的 PR、已关闭的工单以及部署记录汇总成格式化的周报帖
5-代码脚手架与模板
这类 skill 用于为代码库中的某类特定功能生成框架样板代码(boilerplate)。你也可以把它与可组合的脚本搭配使用。当你的脚手架不仅仅是代码模板,还包含一些无法单纯靠代码表达的自然语言要求时,这类 skill 尤其有用。
示例:
• new-<framework>-workflow—— 按照你的注解规范,为新的 service / workflow / handler 生成脚手架• new-migration—— 你的 migration 文件模板,以及常见易踩坑事项• create-app—— 创建一个新的内部应用,并预先接好认证(auth)、日志(logging)和部署配置(deploy config)
6-代码质量与评审
这类 skill 用来在组织内部落实代码质量要求,并辅助开展代码评审。为了获得更高的稳健性,它们可以包含确定性的脚本或工具。你也可以考虑把这些 skill 作为 hooks 的一部分自动运行,或者放进 GitHub Action 中执行。
示例:
• adversarial-review—— 拉起一个拥有“新鲜视角”的子 agent 来挑刺、实施修复,并持续迭代,直到问题退化为吹毛求疵式的小瑕疵• code-style—…