构建 Claude Code 的经验总结:如何使用 Skills「Claude核心开发者百万浏览亲自教学」
Source: http://x.com/i/article/2034143895601483778
原著: @trq212 编译: @0xBennie Skills 已经成为 Claude Code 中最常用的扩展点之一。它们灵活、易于创建,并且易于分发。
但这种灵活性也使得人们很难判断什么是最佳实践。什么类型的 Skill 值得构建?写一个好的 Skill 的关键是什么?什么时候应该与他人分享?
在 Anthropic 内部,我们已经在 Claude Code 中广泛使用 Skills,目前有数百个 Skill 在实际运行。这些是我们在使用 Skills 加速开发过程中总结出的经验。
什么是 Skills?
如果你刚接触 Skills,建议先阅读
或观看
课程,这篇文章默认你已经对 Skills 有一定了解。
Claude的结构层文档
- soul.md → 定义“它是谁”(人格 / 价值观 / 行为底层逻辑)
- claude.md → 定义“它怎么说话”(风格 / 语气 / 输出方式)
- skills.md → 定义“它能做什么”(能力模块 / 工具 / 工作流)
- memory.md → 定义“它记住什么”(长期记忆 / 历史状态)
我们经常听到一个常见的误解:Skills 只是“Markdown 文件”。但 Skills 最有意思的地方在于,它们不仅仅是文本文件,而是一个文件夹,可以包含脚本、资源文件、数据等内容,Agent 可以发现、探索并操作这些内容。
在 Claude Code 中,Skills 还具有多种配置选项,包括注册动态 hooks。
我们发现,在 Claude Code 中最有意思的一些 Skills,往往是那些能够创造性地使用这些配置选项和文件夹结构的。
Skills 的类型
在对所有 Skills 进行归类后,我们发现它们大致集中在几个重复出现的类别中。最好的 Skill 通常会清晰地归属于某一类,而那些让人困惑的 Skill 往往跨越多个类别。
这不是一个绝对完整的列表,但它可以帮助你思考你的组织中是否缺少某些类型的 Skill。
1. 库与 API 参考(Library & API Reference)
这类 Skill 用于解释如何正确使用某个库、CLI 或 SDK。这些既可以是内部库,也可以是 Claude Code 有时处理不好的常见库。
这类 Skill 通常会包含:
- 一组参考代码片段
- 一份 Claude 在编写脚本时需要避免的坑(gotchas)列表
示例:
billing-lib —— 你的内部计费库:边界情况、常见陷阱等 internal-platform-cli —— 你的内部 CLI 包装器的所有子命令,以及何时使用它们的示例 frontend-design —— 让 Claude 更符合你的设计系统
2. 产品验证(Product Verification)
这类 Skill 描述如何测试或验证你的代码是否正常工作。它们通常会与外部工具(如 playwright、tmux 等)配合使用来完成验证。
验证类 Skill 对确保 Claude 输出正确性非常有用。甚至值得让一位工程师花一周时间专门把这类 Skill 打磨到极致。
可以考虑的技术包括:
- 让 Claude 记录其输出过程的视频,从而可以看到它具体测试了什么
- 在每一步对状态执行程序化断言
这些通常通过在 Skill 中包含多种脚本来实现。
示例:
signup-flow-driver —— 在无头浏览器中执行注册 → 邮箱验证 → onboarding,并在每一步提供状态断言 hook checkout-verifier —— 使用 Stripe 测试卡驱动结账 UI,并验证发票是否进入正确状态 tmux-cli-driver —— 用于交互式 CLI 测试(当验证对象需要 TTY 时)
3. 数据获取与分析(Data Fetching & Analysis)
这类 Skill 用于连接你的数据与监控系统。
它们可能包含:
- 获取数据的库(带凭证)
- 特定 dashboard ID
- 常见工作流或数据获取方法说明
示例:
funnel-query —— “要查看注册 → 激活 → 付费,需要关联哪些事件”,以及实际包含 canonical user_id 的表 cohort-compare —— 比较两个 cohort 的留存或转化,并标记统计显著差异,同时附带 segment 定义链接 grafana —— 数据源 UID、集群名称、问题到 dashboard 的映射表
4. 业务流程与团队自动化(Business Process & Team Automation)
这类 Skill 将重复性的工作流程自动化为一条命令。
它们通常是相对简单的指令,但可能依赖其他 Skill 或 MCP。
对于这类 Skill,将之前的执行结果存储在日志文件中,有助于模型保持一致性,并对过去执行进行反思。
示例:
standup-post —— 聚合工单系统、GitHub 活动和之前的 Slack 内容,生成格式化的日报(只包含变化部分) create--ticket —— 强制 schema(合法枚举值、必填字段)并执行创建后的流程(通知 reviewer、同步 Slack) weekly-recap —— 合并 PR、关闭工单、部署记录 → 生成周报
5. 代码脚手架与模板(Code Scaffolding & Templates)
这类 Skill 用于为代码库中的特定功能生成框架模板。
你可以将这类 Skill 与脚本组合使用。它们在存在自然语言要求、无法完全通过代码覆盖的场景中特别有用。
示例:
new--workflow —— 生成带有注解的新服务/工作流/处理器 new-migration —— 迁移文件模板及常见坑 create-app —— 创建新的内部应用,并预配置认证、日志和部署
6. 代码质量与审查(Code Quality & Review)
这类 Skill 用于在组织内部保证代码质量并进行代码评审。
可以包含:
- 确定性脚本
- 工具链
你可能希望将这些 Skill 自动运行,例如:
- 通过 hooks
- 或在 GitHub Action 中执行
示例:
adversarial-review —— 启动一个“全新视角”的子 agent 进行批评、修复,并反复迭代直到问题只剩细节 code-style —— 强制代码风格,尤其是 Claude 默认做不好的部分 testing-practices —— 如何编写测试、测试哪些内容
7. CI/CD 与部署(CI/CD & Deployment)
这类 Skill 用于在代码库中执行:
- 拉取
- 推送
- 部署
它们可能会引用其他 Skill 来获取数据。
示例:
babysit-pr —— 监控 PR → 重试不稳定 CI → 解决合并冲突 → 开启自动合并 deploy- —— 构建 → 冒烟测试 → 渐进式流量发布 → 错误率对比 → 回归自动回滚 cherry-pick-prod —— 独立 worktree → cherry-pick → 冲突解决 → 使用模板创建 PR
8. Runbooks(运行手册 / 排障)
这类 Skill 接收一个症状(例如 Slack 线程、报警或错误特征),然后通过多个工具进行调查,并生成结构化报告。
示例:
-debugging —— 将症状映射到工具与查询模式(针对高流量服务) oncall-runner —— 获取告警 → 检查常见问题 → 输出结果 log-correlator —— 根据 request ID,从所有可能涉及的系统中拉取相关日志
9. 基础设施运维(Infrastructure Operations)
这类 Skill 执行日常维护与运维流程,其中一些可能涉及破坏性操作,因此需要保护机制。
它们可以帮助工程师在关键操作中遵循最佳实践。
示例:
-orphans —— 查找孤立资源 → 发送到 Slack → 观察期 → 用户确认 → 执行清理 dependency-management —— 组织内依赖审批流程 cost-investigation —— “为什么存储/流量成本激增”,并附带具体查询方式
编写 Skills 的技巧
当你决定要构建一个 Skill 时,应该如何编写?
以下是我们总结的一些最佳实践。
不要陈述显而易见的内容
Claude Code 对你的代码库已经有大量了解,同时 Claude 也掌握大量编程知识和默认偏好。
如果你的 Skill 主要是知识型的,请专注于那些能够让 Claude 跳出其默认思维方式的信息。
让AI自己思考该如何去实现,你只需要告诉他你的目标是什么
构建 Gotchas 部分
任何 Skill 中最有价值的内容是 Gotchas 部分。
这些内容应来源于 Claude 在使用该 Skill 时遇到的常见失败点。
理想情况下,你应该随着时间不断更新这些内容。
利用文件系统与渐进式信息披露
正如前面所说,Skill 是一个文件夹,而不仅仅是 Markdown 文件。
你应该将整个文件系统视为一种上下文工程与渐进式披露机制。
你可以告诉 Claude Skill 中有哪些文件,它会在适当的时候读取它们。
最简单的方式是将详细信息拆分到其他 Markdown 文件中,例如:
references/api.md
另一个例子是,如果最终输出是 Markdown 文件,你可以在 assets/ 中提供模板供 Claude 使用。
你可以创建多个文件夹:
- references
- scripts
- examples
从而帮助 Claude 更高效地工作。
避免对 Claude 进行“轨道限制”(Railroading)
Claude 通常会严格遵循你的指令。
由于 Skill 具有高度复用性,你需要避免写得过于具体。
应该提供必要信息,同时保留灵活性。
设计好 Setup
有些 Skill 需要用户提供上下文,例如:
- 将日报发送到哪个 Slack channel
一种良好的做法是将这些配置存储在 skill 目录中的 config.json 文件中。
如果配置不存在,Agent 可以向用户询问。
如果你希望 Agent 提供结构化的多选问题,可以让 Claude 使用 AskUserQuestion 工具。
Description 字段是给模型看的
当 Claude Code 启动时,会生成一个包含所有 Skill 及其 description 的列表。
Claude 会扫描这个列表来判断:
“是否有 Skill 可以处理当前请求?”
因此:
👉 description 不是摘要,而是触发条件说明
记忆与数据存储
某些 Skill 可以通过存储数据来实现“记忆”。
你可以使用:
- 文本日志
- JSON 文件
- SQLite 数据库
例如:
standup-post Skill 可以维护一个 standups.log,记录每次输出,从而在下一次运行时比较变化。
注意:
Skill 目录中的数据在升级时可能会被删除,因此应使用稳定路径,例如:
${CLAUDE_PLUGIN_DATA}
存储脚本并生成代码
你能给 Claude 的最强工具之一就是代码本身。
提供脚本和库可以让 Claude 将精力用于“组合与决策”,而不是重写模板代码。
例如:
在数据科学 Skill 中,你可以提供数据获取函数库。
Claude 可以在此基础上动态生成脚本,完成复杂分析任务,例如:
“周二发生了什么?”
按需 Hooks
Skill 可以包含仅在调用时激活的 hooks,并在会话期间生效。
这适用于:
- 不希望始终启用
- 但在某些场景极其重要的规则
示例:
/careful —— 禁止 rm -rf、DROP TABLE、force-push、kubectl delete /freeze —— 限制编辑范围,仅允许修改特定目录 Skills 的分发
Skills 的一个重要优势是可以与团队共享。
常见方式:
- 将 Skills 放入代码仓库(./.claude/skills)
- 构建插件市场
对于小团队,第一种方式通常足够。
随着规模扩大,内部插件市场更适合分发和管理。
Marketplace 管理
如何决定哪些 Skill 应进入市场?
我们没有集中管理团队,而是采用自然筛选方式。
流程:
- 将 Skill 上传到 GitHub sandbox
- 在 Slack 等渠道分享
- 获得使用后再提交 PR 加入市场
需要注意:
👉 很容易产生低质量或重复 Skill,因此必须有筛选机制
Skill 组合
你可能需要让 Skill 相互依赖。
例如:
- 文件上传 Skill
- CSV 生成 Skill
目前没有原生依赖系统,但可以通过名称引用其他 Skill,模型会在安装后自动调用。
Skill 评估
我们使用 PreToolUse hook 来记录 Skill 的使用情况,从而:
- 找出热门 Skill
- 识别触发率异常的 Skill
结论
Skills 是 Agent 极其强大且灵活的工具,但目前仍处于早期阶段。
本文更像是一个经验集合,而非权威指南。
理解 Skills 的最佳方式是:
👉 亲自构建并实验
我们的大多数 Skill 最初只是:
- 几行代码
- 一个简单的坑
然后随着 Claude 遇到新的边界情况而不断演化。
只有不断向 AI 的边界推进,才有机会触及其真正的深层结构。
https://x.com/trq212/status/2033949937936085378