实战 | 构建 Claude Code 的经验：我们如何使用 Skills
文章来源
本文编译自 Thariq Shihipar（@trq212）在 X 上发布的长文 Lessons from Building Claude Code: How We Use Skills，发布于 2026 年 3 月 17 日。
Thariq 是 Anthropic Claude Code 团队工程师，也是 Skills 功能的核心推动者之一。加入 Anthropic 之前，他在 MIT Media Lab 读研期间联合创建了开源学术发布平台 PubPub，后来参加了 Y Combinator（W20 批次）。他在文中以 Anthropic 内部视角，分享了数百个活跃 Skills 背后的分类体系、编写心法与分发策略。
主要观点
- Skills 不只是 markdown：它们是文件夹——包含脚本、资源、数据，智能体可以发现、探索和使用这些内容。
- 9 大类型：库与 API 参考、产品验证、数据获取与分析、业务流程自动化、代码脚手架、代码质量与审查、CI/CD 与部署、运维手册、基础设施运维。
- 编写心法：不说显而易见的事、建踩坑点章节、利用文件系统做渐进式披露、不要把 Claude 限制太死、description 字段是写给模型看的。
- 分发策略：小团队提交到仓库
.claude/skills即可；大规模团队用插件市场（Plugin Marketplace）让成员自选安装。 - 核心判断：Skills 是 AI 智能体极其强大且灵活的工具，但一切还处于早期阶段——最好的方式就是动手做、不断试验。
译文
Skills 已经成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、容易制作，分发也很简单。
但也正因为太灵活，你很难知道怎样用才最好。什么类型的 Skills 值得做？写出好 Skill 的秘诀是什么？什么时候该分享给别人？
我们在 Anthropic 内部大量使用 Claude Code 的 Skills，目前活跃使用的已经有几百个。以下就是我们在用 Skills 加速开发过程中总结出的经验。
什么是 Skills？
如果你还不了解 Skills，建议先看看我们的文档或 Skilljar 上关于 Agent Skills 的课程，本文假设你已经对 Skills 有了基本的了解。
我们经常听到一个误解，认为 Skills「只不过是 markdown 文件」。但 Skills 最有意思的地方恰恰在于它们不只是文本文件——它们是文件夹，可以包含脚本、资源文件、数据等等，智能体可以发现、探索和使用这些内容。
在 Claude Code 中，Skills 还拥有丰富的配置选项，包括注册动态钩子（hooks）。
我们发现，Claude Code 中最有意思的那些 Skills，往往就是创造性地利用了这些配置选项和文件夹结构。
Skills 的类型
在梳理了我们所有的 Skills 之后，我们注意到它们大致可以归为几个反复出现的类别。最好的 Skills 清晰地落在某一个类别里；让人困惑的 Skills 往往横跨了好几个。这不是一份终极清单，但如果你想检查团队里是否还缺了什么类型的 Skills，这是一个很好的起点。
1. 库与 API 参考
帮助你正确使用某个库、命令行工具或 SDK 的 Skills。既可以针对内部库，也可以针对 Claude Code 偶尔会犯错的常用库。通常包含一组参考代码片段，以及 Claude 写代码时需要避免的踩坑点列表。
示例：
billing-lib— 内部计费库：边界情况、容易踩的坑internal-platform-cli— 内部 CLI 工具的每个子命令及使用场景frontend-design— 让 Claude 更好地理解你的设计系统
2. 产品验证
描述如何测试或验证代码是否正常工作的 Skills。通常会搭配 Playwright、tmux 等外部工具完成验证。
验证类 Skills 对确保 Claude 输出的正确性非常有用。值得安排一个工程师花上一周时间专门打磨你的验证 Skills。
可以考虑的技巧：让 Claude 录制输出过程的视频，这样你能看到它到底测试了什么；或者在每一步强制执行程序化的状态断言。这些通常通过在 Skill 中包含各种脚本来实现。
示例：
signup-flow-driver— 在无头浏览器中跑完注册→邮件验证→引导流程，每一步插入状态断言checkout-verifier— 用 Stripe 测试卡驱动结账 UI，验证发票最终状态tmux-cli-driver— 针对需要 TTY 的交互式命令行测试
3. 数据获取与分析
连接你的数据和监控体系的 Skills。可能包含带凭证的数据获取库、特定的仪表盘 ID 等，以及常用工作流和数据获取方式的说明。
示例：
funnel-query— 「要看注册→激活→付费的转化，需要关联哪些事件？」再加上规范 user_id 所在的表cohort-compare— 对比两个用户群的留存或转化率，标记统计显著的差异grafana— 数据源 UID、集群名称、问题→仪表盘对照表
4. 业务流程与团队自动化
把重复性工作流自动化为一条命令的 Skills。通常指令比较简单，但可能依赖其他 Skills 或 MCP。对于这类 Skills，把之前的执行结果保存在日志文件中，有助于模型保持一致性并反思之前的执行情况。
示例：
standup-post— 汇总任务追踪器、GitHub 活动和之前的 Slack 消息→生成格式化站会汇报create-<ticket-system>-ticket— 强制执行 schema 加上创建后的工作流（通知审查者、在 Slack 中发链接）weekly-recap— 已合并的 PR + 已关闭的工单 + 部署记录→格式化的周报
5. 代码脚手架与模板
为代码库中的特定功能生成框架样板代码的 Skills。可以和脚本组合使用。当你的脚手架有自然语言需求、无法纯靠代码覆盖时，这类 Skills 特别有用。
示例：
new-<framework>-workflow— 用你的注解搭建新的服务/工作流/处理器new-migration— 数据库迁移文件模板加上常见踩坑点create-app— 新建内部应用，预配好认证、日志和部署配置
6. 代码质量与审查
在团队内部执行代码质量标准并辅助代码审查的 Skills。可以包含确定性的脚本或工具来保证可靠性。你可能希望把这些 Skills 作为钩子自动运行，或放在 GitHub Action 中执行。
示例：
adversarial-review— 生成一个全新视角的子智能体来挑刺，实施修复，反复迭代直到发现的问题退化为吹毛求疵code-style— 强制执行代码风格，特别是 Claude 默认做不好的风格testing-practices— 关于如何写测试以及测试什么的指导
译注：子智能体（subagent）是指 Claude Code 在执行任务时启动的另一个独立 Claude 实例。这里的做法是让一个「没见过这段代码」的新实例来做代码审查，避免原实例的思维惯性。
7. CI/CD 与部署
帮你拉取、推送和部署代码的 Skills。可能会引用其他 Skills 来收集数据。
示例：
babysit-pr— 监控 PR→重试不稳定的 CI→解决合并冲突→启用自动合并deploy-<service>— 构建→冒烟测试→渐进式流量切换并对比错误率→指标恶化时自动回滚cherry-pick-prod— 隔离的工作树→cherry-pick→解决冲突→用模板创建 PR
8. 运维手册
接收一个现象（如一条 Slack 消息、告警或错误特征），引导你走完多工具排查流程，最后生成结构化报告的 Skills。
示例：
<service>-debugging— 把现象对应到工具→查询模式，覆盖流量最大的服务oncall-runner— 拉取告警→检查常见嫌疑→格式化输出排查结论log-correlator— 给定一个请求 ID，从所有可能经过的系统中拉取匹配的日志
9. 基础设施运维
执行日常维护和运维操作的 Skills——其中一些涉及破坏性操作，需要安全护栏。这些 Skills 让工程师在执行关键操作时更容易遵循最佳实践。
示例：
<resource>-orphans— 找到孤立的 Pod/Volume→发到 Slack→等待观察→用户确认→级联清理dependency-management— 组织的依赖审批工作流cost-investigation— 「存储/出口带宽费用为什么突然涨了」，附带具体的存储桶和查询模式
编写 Skills 的技巧
确定了要做什么 Skill 之后，怎么写？以下是我们总结的最佳实践。
不要说显而易见的事
Claude Code 对你的代码库已经非常了解，Claude 本身对编程也很在行。如果你的 Skill 主要是提供知识，那就把重点放在能打破 Claude 常规思维模式的信息上。
frontend-design 这个 Skill 就是很好的例子——它是 Anthropic 的一位工程师通过与用户反复迭代、改进 Claude 的设计品味而构建的，专门避免那些典型的套路，比如 Inter 字体和紫色渐变。
建一个踩坑点章节
任何 Skill 中信息量最大的部分就是踩坑点章节。这些章节应该根据 Claude 使用你的 Skill 时遇到的常见失败点逐步积累。理想情况下，你会持续更新 Skill 来记录这些踩坑点。
利用文件系统与渐进式披露
Skill 是一个文件夹，不只是一个 markdown 文件。你应该把整个文件系统当作**上下文工程（Context Engineering）和渐进式披露（Progressive Disclosure）**的工具。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时候去读取它们。
译注：上下文工程是 2025 年由 Andrej Karpathy 等人提出并广泛传播的概念，指精心设计和管理输入给大语言模型的上下文信息，以最大化模型的输出质量。渐进式披露借用了 UI 设计概念，意思是不一次性把所有信息塞给模型，而是让它在需要时再去读取，从而节省上下文窗口空间。
最简单的渐进式披露形式是指向其他 markdown 文件让 Claude 使用。例如，你可以把详细的函数签名和用法示例拆分到 references/api.md 里。
另一个例子：如果你的最终输出是一个 markdown 文件，你可以在 assets/ 中放一个模板文件供复制使用。
你可以有参考资料、脚本、示例等文件夹，帮助 Claude 更高效地工作。
不要把 Claude 限制得太死
Claude 通常会努力遵循你的指令，而由于 Skills 的复用性很强，你需要注意不要把指令写得太具体。给 Claude 它需要的信息，但留给它适应具体情况的灵活性。
考虑好初始设置
有些 Skills 可能需要用户提供上下文来完成初始设置。例如，如果你做了一个把站会内容发到 Slack 的 Skill，你可能希望 Claude 先问用户要发到哪个 Slack 频道。
一个好的做法是把这些设置信息存在 Skill 目录下的 config.json 文件里。如果配置还没设置好，智能体就会向用户询问相关信息。
description 字段是给模型看的
当 Claude Code 启动一个会话时，它会构建一份所有可用 Skills 及其描述的清单。Claude 通过扫描这份清单来判断「这个请求有没有对应的 Skill？」所以 description 字段不是摘要——它描述的是何时该触发这个 Skill。
译注：很多人写 description 时会写「这个 Skill 做什么」，但 Claude 需要的是「什么情况下该用这个 Skill」。好的 description 读起来更像 if-then 条件，而不是功能说明。
记忆与数据存储
有些 Skills 可以通过在内部存储数据来实现某种形式的记忆。你可以用最简单的方式——一个只追加写入的文本日志文件或 JSON 文件，也可以用更复杂的方式——比如 SQLite 数据库。
例如，一个 standup-post Skill 可以保留一份 standups.log，记录它写过的每一条站会汇报。这样下次运行时，Claude 会读取自己的历史记录，就能知道从昨天到现在发生了什么变化。
存在 Skill 目录下的数据可能会在升级 Skill 时被删除，所以应该把数据存在一个稳定的文件夹中。目前 Claude Code 提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定数据存储目录。
存储脚本与生成代码
你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，让它把精力花在组合编排上——决定下一步做什么，而不是重新构造样板代码。
例如，在你的数据科学 Skill 中，你可以放一组从事件源获取数据的函数库。
Claude 就可以即时生成脚本来组合这些功能，完成更高级的分析——比如回答「周二发生了什么？」这样的问题。
按需钩子
Skills 可以包含只在该 Skill 被调用时才激活的钩子（On Demand Hooks），并且在整个会话期间保持生效。这适合那些比较主观、你不想一直运行但有时候极其有用的钩子。
示例：
/careful— 通过 PreToolUse 匹配器拦截 Bash 中的rm -rf、DROP TABLE、force-push、kubectl delete。你只在操作生产环境时才需要这个——要是一直开着会让你抓狂。/freeze— 阻止对特定目录之外的任何 Edit/Write 操作。在调试时特别有用：「我想加日志但老是不小心『修』了不相关的代码」。
译注：PreToolUse 是 Claude Code 的钩子机制之一，会在 Claude 每次调用工具之前触发。你可以在这个钩子里检查 Claude 即将执行的命令，如果命中危险操作就阻止执行。
分发 Skills
Skills 最大的好处之一就是你可以把它们分享给团队的其他人。
你可以通过两种方式分享 Skills：
- 把 Skills 提交到你的代码仓库中（放在
./.claude/skills下） - 做成插件，搭建一个 Claude Code 插件市场（Plugin Marketplace），让用户可以上传和安装插件
对于在较少代码仓库上协作的小团队，提交到仓库就够了。但每个提交进去的 Skill 都会给模型的上下文增加一点负担。随着规模扩大，内部插件市场可以让你分发 Skills，同时让团队成员自己决定安装哪些。
管理插件市场
我们没有一个专门的中心团队来决定这些事；我们更倾向于让最有用的 Skills 自然涌现。如果你有一个想让大家试试的 Skill，可以把它上传到 GitHub 的一个沙盒文件夹里，然后在 Slack 或其他论坛里推荐给大家。
当一个 Skill 获得了足够的关注（由 Skill 的作者自己判断），就可以提交 PR 把它移到插件市场中。
需要提醒的是，创建质量差或重复的 Skills 很容易，所以在正式发布之前确保有某种审核机制很重要。
组合 Skills
你可能希望 Skills 之间互相依赖。例如，你可能有一个文件上传 Skill 用来上传文件，以及一个 CSV 生成 Skill 用来生成 CSV 并上传。这种依赖管理目前在插件市场或 Skills 中还不支持，但你可以直接按名字引用其他 Skills，只要对方已安装，模型就会调用它们。
衡量 Skills 的效果
为了了解一个 Skill 的表现，我们使用了一个 PreToolUse 钩子来在公司内部记录 Skill 的使用情况。这样我们就能发现哪些 Skills 很受欢迎，或者哪些触发频率低于预期。
结语
Skills 是 AI 智能体极其强大且灵活的工具，但这一切还处于早期阶段，我们都在摸索怎样用好它们。
与其把这篇文章当作权威指南，不如把它看作我们实践中验证过有效的一堆实用技巧合集。理解 Skills 最好的方式就是动手开始做、不断试验、看看什么对你管用。我们大多数 Skills 一开始就是几行文字加一个踩坑点，后来因为大家不断补充 Claude 遇到的新边界情况，才慢慢变好的。
原文作者：Thariq Shihipar，Anthropic Claude Code 工程师。