Claude Code Skills 完整教程：Anthropic 官方是怎么用 Skill 的？

1. 库和 API 参考

这类 Skills 用于说明如何正确使用库、CLI 或 SDK。它们既可以面向内部库，也可以面向 Claude Code 有时难以正确处理的常用库。这类 Skills 通常包含一个存放参考代码片段的文件夹，以及一份注意事项清单，帮助 Claude 在编写脚本时避开常见陷阱。

示例包括：

• billing-lib — 你的内部计费库：边界情况、易踩的坑等。
• internal-platform-cli — 你的内部 CLI 封装中每个子命令的说明，以及应在何时使用它们的示例。
• sandbox-proxy — 为开发工作配置组织的出口网关：哪些主机可以访问、如何调试“connection refused”错误，以及如何添加 allowlist 条目。

2. 产品验证

这类 Skills 用于说明如何测试或验证代码是否正常工作。它们通常会与 playwright、tmux 或其他外部验证工具配合使用。

在 Anthropic 内部，验证类 Skills 对 Claude 输出质量的改善最为显著且可量化。让一位工程师花一周时间专门把验证类 Skills 做到出色，可能非常值得。

可以考虑让 Claude 录制其输出的视频，以便你准确看到它测试了什么；或者要求它在每一步都通过程序化断言验证状态。这些能力通常通过在 Skill 中包含各种脚本来实现。

示例包括：

• signup-flow-driver — 在无头浏览器中完整执行注册 → 邮箱验证 → 新手引导流程，并提供可在每一步断言状态的 Hooks
• checkout-verifier — 使用 Stripe 测试卡驱动结账 UI，并验证发票是否真正进入了正确状态
• tmux-cli-driver — 用于交互式 CLI 测试，适合被验证对象需要 TTY 的情况

3. 数据获取和分析

这类 Skills 用于连接你的数据和监控技术栈。它们可能包含使用凭证获取数据的库、特定的 dashboard id 等，以及有关常见工作流或数据获取方式的说明。

示例包括：

• funnel-query — “要查看注册 → 激活 → 付费，需要关联哪些事件”，以及真正存放规范 user_id 的表
• cohort-compare — 比较两个 cohort 的留存率或转化率，标记具有统计显著性的差异，并链接到用户分群定义
• grafana — 数据源 UID、集群名称，以及问题 → dashboard 的查找表
• datadog — 字段参考（@request_id 与 trace_id）、服务列表以及指标前缀约定

4. 业务流程和团队自动化

这类 Skills 能把重复性工作流自动化为一条命令。它们通常只是相当简单的说明，但可能会更复杂地依赖其他 Skills 或 MCP。对于这类 Skills，将先前的结果保存在日志文件中，可以帮助模型保持一致，并回顾该工作流此前的执行情况。

示例包括：

• standup-post — 汇总你的工单跟踪系统、GitHub 活动和先前的 Slack 内容 → 生成格式化的站会汇报，仅包含变化
• create-<ticket-system>-ticket — 强制执行 schema（有效的枚举值、必填字段），并完成创建后的工作流（通知评审者、在 Slack 中发布链接）
• weekly-recap — 已合并的 PR + 已关闭的工单 + 部署记录 → 格式化的每周回顾帖

5. 代码脚手架和模板

这类 Skills 用于为代码库中的特定功能生成框架样板代码。你可以将这类 Skills 与能够组合使用的脚本结合起来。当脚手架存在无法完全通过代码表达的自然语言要求时，它们尤其有用。

示例包括：

• new-<framework>-workflow — 使用你的注解为新服务、工作流或 handler 搭建脚手架
• new-migration — 你的 migration 文件模板及常见注意事项
• create-app — 创建新的内部应用，并预先接好身份验证、日志和部署配置

6. 代码质量和评审

这类 Skills 用于在组织内部落实代码质量标准并协助评审代码。为了最大程度地提高稳健性，它们可以包含确定性的脚本或工具。你可能需要通过 Hooks 或在 GitHub Action 中自动运行这些 Skills。

• adversarial-review — 启动一个以全新视角进行审查的 Subagent，让它提出批评意见、实施修复并反复迭代，直到发现的问题只剩吹毛求疵的小问题
• code-style — 强制执行代码风格，尤其是 Claude 默认情况下不擅长遵循的风格。
• testing-practices — 有关如何编写测试以及应测试哪些内容的说明。

7. CI/CD 和部署

这类 Skills 帮助你在代码库中获取、推送和部署代码。它们可能会引用其他 Skills 来收集数据。

示例包括：

• babysit-pr — 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并
• deploy-<service> — 构建 → 冒烟测试 → 逐步放量并比较错误率 → 出现回归时自动回滚
• cherry-pick-prod — 隔离的 worktree → cherry-pick → 解决冲突 → 使用模板创建 PR

8. Runbooks

这类 Skills 从某个症状入手（例如 Slack 讨论串、告警或错误特征），引导完成跨多个工具的调查，并生成结构化报告。

示例包括：

• <service>-debugging — 针对流量最高的服务，将症状 → 工具 → 查询模式对应起来
• oncall-runner — 获取告警 → 检查常见问题来源 → 格式化调查结果
• log-correlator — 给定一个 request ID，从所有可能处理过该请求的系统中拉取匹配的日志

9. 基础设施运维

这类 Skills 用于执行日常维护和运维流程，其中有些涉及破坏性操作，因此会受益于防护措施。它们能让工程师在关键操作中更轻松地遵循最佳实践。

示例包括：

• <resource>-orphans — 查找孤立的 pod/volume → 发布到 Slack → 观察期 → 用户确认 → 级联清理
• dependency-management — 你所在组织的依赖审批工作流
• cost-investigation — “为什么我们的存储/出口流量账单突然增加”，并附上具体的 bucket 和查询模式

制作 Skills 的技巧

确定要制作什么 Skill 之后，该如何编写它？以下是 Claude Code 团队在制作 Skills 方面总结的一些最佳实践、技巧和诀窍。

不要陈述显而易见的内容

Claude 已经知道如何编程，也能阅读你的代码库。一个只是重复 Claude 默认会做之事的 Skill，只会增加 Context，却不会增加价值。如果你发布的 Skill 主要用于传递知识，请专注于那些能够推动 Claude 跳出常规思维方式的信息。

前端设计 Skill就是一个很好的例子；它由 Anthropic 的一位工程师通过与客户反复迭代构建而成，目标是改善 Claude 的设计品位，避免 Inter 字体和紫色渐变等经典套路。

编写注意事项章节

任何 Skill 中信息密度最高的内容都是“注意事项”章节。这些章节应该根据 Claude 使用你的 Skill 时经常遇到的失败点逐步构建。理想情况下，你应当持续更新 Skill，把这些注意事项记录下来。

例如：

“subscriptions 表只允许追加。你需要的是版本号最高的那一行，而不是 created_at 最新的那一行。”“这个字段在 API gateway 中叫作 @request_id，在 billing service 中叫作 trace_id。它们是同一个值。”“即使 Stripe webhook 实际上没有处理成功，Staging 也会返回 200。请检查 payment_events 以确认真实状态。”

使用文件系统和渐进式披露

SKILL.md 文件指向多个其他文件，Claude 可以在特定情况下查阅它们。例如，如果某个任务一直处于 pending 状态，就应该查阅 stuck-jobs.md。

正如我们前面所说，Skill 是一个文件夹，而不只是一个 Markdown 文件。你应该把整个文件系统视为 Context Engineering 和渐进式披露的一种形式。告诉 Claude 你的 Skill 中有哪些文件，它就会在适当的时候读取这些文件。

最简单的渐进式披露方式，是指向其他可供 Claude 使用的 Markdown 文件。例如，你可以把详细的函数签名和使用示例拆分到 references/api.md 中。

再举一个例子：如果最终输出是一个 Markdown 文件，你可以在 assets/ 中放入一个模板文件，供 Claude 复制和使用。

你可以建立存放参考资料、脚本、示例等内容的文件夹，帮助 Claude 更高效地工作。

避免把 Claude 限制在固定路径上

Claude 通常会尽力遵循你的说明，而由于 Skills 具有很强的复用性，你需要小心，不要把说明写得过于具体。向 Claude 提供所需信息，同时也要给它根据实际情况灵活调整的空间。

例如：

仔细考虑初始化设置

上面的 Skill 被编写为：如果配置中未包含 Slack 频道，就提示用户提供。

有些 Skills 可能需要使用用户提供的 Context 进行初始化设置。例如，如果你正在制作一个把站会汇报发布到 Slack 的 Skill，你可能希望 Claude 询问应将内容发布到哪个 Slack 频道。

一个很好的做法是，像上面的例子一样，把这些初始化信息存储在 Skill 目录中的 config.json 文件里。如果尚未完成配置，Agent 就可以向用户询问信息。

如果你希望 Agent 提出结构化的选择题，可以指示 Claude 使用 AskUserQuestion 工具。

为模型而不是人类编写描述

Claude Code 启动 Session 时，会生成一份包含所有可用 Skills 及其描述的列表。Claude 会扫描这份列表，以判断“是否存在适合这个请求的 Skill？”这意味着 description 字段并不是摘要，而是关于何时触发这个 Skill 的说明。

在描述中加入该 Skill 的触发词（例如“babysit”）会很有帮助。

‍

帮助 Claude 记忆

这个文本日志文件帮助 Claude 记住过去发生的事件，例如评审 Sarah 的身份验证 PR。

有些 Skills 可以通过在内部存储数据来提供某种形式的记忆能力。数据的存储方式既可以简单到只是一个只允许追加的文本日志文件或 JSON 文件，也可以复杂到使用 SQLite 数据库。

例如，一个 standup-post Skill 可以通过 standups.log 保存它编写过的每一篇站会汇报。这样，下次运行时，Claude 就能读取自己的历史记录，并判断自昨天以来发生了哪些变化。

你可以使用环境变量 ${CLAUDE_PLUGIN_DATA} 获取一个可用于存储数据的稳定目录；有关在 Skills 中持久化数据的更多信息，请参阅：https://code.claude.com/docs/en/plugins-reference#persistent-data-directory。

存储脚本并生成代码

你能提供给 Claude 的最强大工具之一就是代码。向 Claude 提供脚本和库，可以让它把每轮交互用于组合现有能力和决定下一步做什么，而不是重新构建样板代码。

例如，在你的 data-science Skill 中，可以准备一个函数库，用来从事件数据源获取数据。为了让 Claude 能够执行复杂分析，你可以为它提供如下的一组辅助函数：

随后，Claude 可以动态生成脚本，将这些功能组合起来，从而对“周二发生了什么？”之类的 Prompt 执行更高级的分析。

使用按需 Hooks

Skills 可以包含仅在 Skill 被调用时激活、并且只在当前 Session 持续期间有效的 Hooks。你可以借此加入一些倾向性更强、不希望一直运行但有时又极其有用的 Hooks。

例如：

• /careful— 通过 Bash 上的 PreToolUse matcher 阻止 rm -rf、DROP TABLE、force-push 和 kubectl delete。只有在你明确知道自己正在操作生产环境时才会需要它——如果它始终开启，会把你逼疯。
• /freeze — 阻止对特定目录之外的任何 Edit/Write 操作。在调试期间很有用：“我想添加日志，但总是不小心‘修复’了无关代码。”

分发 Skills

Skills 最大的优势之一，是你可以与团队中的其他人共享它们。

你可能希望通过两种方式与他人共享 Skills：

• 将 Skills 提交到你的代码仓库中（位于 ./.claude/skills 下）
• 制作一个 plugin，并建立一个 Claude Code Plugin marketplace，让用户可以上传和安装 plugins（可在文档中阅读更多信息）

对于只需要处理相对较少代码仓库的小型团队，把 Skills 提交到代码仓库中很有效。但每个提交到仓库中的 Skill 也会略微增加模型的 Context。随着规模扩大，内部 plugin marketplace 可以帮助你分发 Skills，让团队成员自行决定要安装哪些 Skills，同时还能加入初始化设置流程。

管理 Skills marketplace

如何决定哪些 Skills 应该进入 marketplace？人们又该如何提交它们？

在 Anthropic，我们没有一个负责决策的中心化团队；相反，我们会尝试以自然演进的方式找到最有用的 Skills。如果有人希望大家试用自己的 Skill，可以把它上传到 GitHub 中的 sandbox 文件夹，然后在 Slack 或其他论坛中向大家分享。

当某个 Skill 获得一定使用量后（具体标准由 Skill 所有者决定），所有者就可以提交 PR，将它移入 marketplace。

组合 Skills

你可能希望创建彼此依赖的 Skills。例如，你可能有一个负责上传文件的文件上传 Skill，以及一个生成 CSV 并将其上传的 CSV 生成 Skill。这类依赖管理目前还没有原生内置于 marketplaces 或 Skills 中，但你可以直接按名称引用其他 Skills；如果它们已经安装，模型就会调用它们。

衡量 Skills

为了了解一个 Skill 的表现，我们会使用 PreToolUse Hook 记录公司内部的 Skill 使用情况（示例代码见此处）。这样，我们就能找出受欢迎的 Skills，或者那些触发频率低于预期的 Skills。

开始使用

Skills 的最佳实践仍在不断演进。我们最好的 Skills 大多起初只有几行文字和一个注意事项，后来随着 Claude 遇到新的边界情况，人们持续向其中添加内容，它们才变得越来越好。

理解 Skills 的最佳方式，就是开始使用、不断实验，并看看什么最适合你。

• 查看我们的 Skills 文档
• 查找可供定制的 Skills 示例

本文由 Anthropic 技术团队成员 Thariq Shihipar 撰写，他从事 Claude Code 相关工作。