Claude Code技能实践指南 用法解析与设计心得

本文面向所有关注 Claude Code 并希望深化 Agent 工作流应用的开发者。作者 Thariq Shihipar 作为 Anthropic 内部 Claude Code 项目的核心建设者，分享了团队在实战中沉淀的 Skills 设计与应用经验。这些并非抽象理论，而是基于内部数百个活跃 Skills 总结出的宝贵实践。

对于已经入门 Agent 工程的开发者而言，这类关于 Skills 分类、编写规范、团队分发及管理的一手洞见，往往比官方产品文档更具参考价值。

Skills 已成为 Claude Code 生态中最受欢迎的扩展功能之一，其核心优势在于灵活性高、制作简单且易于分享。

然而，正是这种高度的灵活性，也让许多开发者面临选择困境：什么样的 Skill 值得投入精力？编写高质量 Skill 的关键技巧是什么？何时应该将其分享给团队？

Anthropic 内部团队已在 Claude Code 中大规模应用 Skills，目前有数百个活跃 Skill 在日常工作中发挥作用。以下是从中提炼出的核心经验与最佳实践。

Skills 的核心概念

如果你是 Skills 的新手，建议先阅读官方文档；本文假设你已经具备基础了解。

一个常见的误解是认为 Skills “仅仅是 Markdown 文件”。

实际上，Skills 的真正魅力在于其是一个完整的文件夹，内部可以包含脚本、资源文件、数据等多样化内容，Agent 能够发现、浏览并操作这些资源。

在 Claude Code 中，Skills 还支持丰富的配置选项，包括注册动态钩子（hooks）。实践中发现，一些最具创意的 Skill 正是巧妙地利用了这些配置选项与文件夹结构来实现的。

Skills 的常见类型

在梳理内部所有 Skills 后，我们发现它们通常会聚合到几个反复出现的类别中。优秀的 Skill 往往能清晰地归属于某一类别；而那些令人困惑的 Skill，通常是试图跨越多个类别。以下分类并非穷举，但可以作为一个有效的思考框架，帮助你评估团队中是否缺少某些关键类型的 Skill。

1-库与 API 参考

这类 Skill 旨在指导如何正确使用特定的库、CLI 工具或 SDK。它既可以针对内部私有库，也可以覆盖那些 Claude Code 可能掌握不牢的常用公共库。通常会附带参考代码片段目录和一份“常见陷阱（Gotchas）”清单，帮助 Claude 在编写脚本时规避典型错误。

示例：

• billing-lib —— 内部计费库的使用指南：涵盖边界情况、隐藏陷阱等
• internal-platform-cli —— 内部 CLI 封装器的所有子命令详解及适用场景示例
• frontend-design —— 帮助 Claude 更好地遵循团队的设计系统规范

2-产品功能验证

这类 Skill 用于描述如何测试或验证代码功能是否正常工作。它们常与外部工具（如 Playwright、tmux 等）结合，以完成自动化验证流程。

验证类 Skill 对于确保 Claude 的输出准确性至关重要。有时，投入一位工程师一周时间，将一个关键验证类 Skill 打磨到极致，是非常值得的投资。

可以考虑采用以下技巧：让 Claude 录制输出过程的视频，以便精确查看测试内容；或在每一步骤中加入可编程检查的状态断言。这些能力通常通过在 Skill 中集成多种脚本来实现。

示例：

• signup-flow-driver —— 在无头浏览器中完整执行“注册 → 邮箱验证 → 新手引导”流程，并在每一步提供状态断言钩子
• checkout-verifier —— 使用 Stripe 测试卡驱动结账界面，并验证发票是否进入正确状态
• tmux-cli-driver —— 用于交互式 CLI 测试，适用于必须在 TTY 环境中运行的验证场景

3-数据获取与分析

这类 Skill 负责连接你的数据体系与监控体系。它们可能包含用于凭证认证的数据获取库、特定仪表板的 ID，以及常见工作流说明或标准数据查询方法。

示例：

• funnel-query —— 说明“若要分析注册 → 激活 → 付费转化漏斗，需要关联哪些事件表”，并指出规范 user_id 存储的真实表
• cohort-compare —— 比较两个用户群的留存或转化率，标出具有统计显著性的差异，并链接到对应的细分定义
• grafana —— 提供数据源 UID、集群名称，以及“问题现象 → 对应仪表板”的查询映射表

4-业务流程与团队自动化

这类 Skill 将重复性工作流自动化为一键命令。它们通常是相对简单的指令集合，但有时也可能依赖其他 Skills 或 MCP（模型上下文协议）。对于此类 Skill，将历史执行结果保存到日志文件中，有助于模型保持上下文一致性并回顾过往执行情况。

示例：

• standup-post —— 汇总工单跟踪器、GitHub 活动及之前的 Slack 内容，生成格式化的站会报告，仅输出增量变化
• create--ticket —— 强制执行 Schema 约束（如合法枚举值、必填字段），并完成建单后的后续流程（通知评审人、将链接发布到 Slack）
• weekly-recap —— 将已合并的 PR、已关闭的工单以及部署记录汇总成格式化的周报

5-代码脚手架与模板

这类 Skill 用于为代码库中的特定功能生成框架样板代码。你也可以将其与可组合的脚本搭配使用。当你的脚手架不仅包含代码模板，还涉及无法仅用代码表达的自然语言要求时，这类 Skill 尤其有用。

示例：

• new--workflow —— 按照团队的注解规范，为新的服务、工作流或处理器生成脚手架
• new-migration —— 数据库迁移文件模板，以及常见易错点提醒
• create-app —— 创建新的内部应用，并预先集成认证、日志和部署配置

6-代码质量与评审

这类 Skill 用于在组织内部落实代码质量标准并辅助代码评审。为了获得更高的稳健性，它们可以包含确定性的脚本或工具。你也可以考虑将这些 Skill 作为钩子自动运行，或集成到 GitHub Action 中。

示例：

• adversarial-review —— 启动一个拥有“全新视角”的子 Agent 来挑刺、实施修复并持续迭代，直到问题退化为吹毛求疵的小瑕疵
• code-style —— 强制执行代码风格规范，尤其适用于 Claude 默认处理不佳的特定风格要求
• testing-practices —— 说明测试应如何编写以及具体的测试范围

7-CI/CD 与部署

这类 Skill 帮助你在代码库中完成拉取、推送与部署等操作。它们也可能引用其他 Skills 来收集所需数据。

示例：

• babysit-pr —— 监控 PR → 重试不稳定的 CI 构建 → 解决合并冲突 → 开启自动合并
• deploy- —— 执行构建 → 冒烟测试 → 逐步放量上线，并比较错误率 → 出现回归时自动回滚
• cherry-pick-prod —— 创建隔离的工作树 → 执行代码拣选 → 解决冲突 → 按模板发起 PR

8-处置手册（Runbooks）

这类 Skill 从特定症状出发（例如一条 Slack 讨论串、一个告警或某种错误特征），引导你完成跨工具的排查链路，并最终生成结构化报告。

示例：

• -debugging —— 为高流量服务建立“症状 → 排查工具 → 查询模式”的映射关系
• oncall-runner —— 拉取告警 → 检查常见嫌疑项 → 输出格式化的排查结论
• log-correlator —— 给定一个请求 ID，从所有可能处理过该请求的系统中拉取匹配的日志

9-基础设施运维

这类 Skill 用于执行日常维护与运维操作。由于部分操作具有破坏性，特别适合配备安全护栏。它们能让工程师在关键操作中更轻松地遵循最佳实践。

示例：

• -orphans —— 找出孤立的 Pods / 存储卷 → 发布到 Slack → 经过一段观察期 → 用户确认 → 级联清理
• dependency-management —— 团队内部的依赖项审批工作流
• cost-investigation —— 调查“存储或出网流量费用为何突然飙升”，并提供对应的存储桶与查询模式

Skills 制作的最佳实践

当你决定制作某个 Skill 后，应如何着手编写？以下是从大量实践中总结出的建议、技巧与经验。

最近更新的 Skill Creator 功能，也让在 Claude Code 中创建 Skills 变得更加便捷。

1-避免陈述显而易见的内容

Claude Code 对你的代码库已有相当了解，而 Claude 本身也掌握了大量编程知识并具备默认判断力。因此，如果你发布的是一个知识型 Skill，应聚焦于那些能打破 Claude 常规思维模式的关键信息。

frontend-design 这个 Skill 就是一个优秀范例。它由 Anthropic 的一位工程师在与客户反复迭代中打磨而成，目标是提升 Claude 的设计品味，并帮助其避开一些经典设计套路，例如过度使用 Inter 字体和紫色渐变。

2-建立“常见陷阱”清单

在任何 Skill 中，信号最强、价值最高的部分往往是 Gotchas（常见陷阱）。这部分应围绕 Claude 在使用该 Skill 时反复遇到的典型失败点持续积累。理想情况下，你应该随时间推移不断更新 Skill，补充新发现的陷阱。

3-善用文件系统与渐进式披露

如前所述，Skill 是一个文件夹，而非单个 Markdown 文件。你应该将整个文件系统视为上下文工程与渐进式披露的一部分。只需告诉 Claude 你的 Skill 目录中包含哪些文件，它就会在适当时机读取它们。

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

再比如，如果你的最终输出是一个 Markdown 文件，你可以在 assets/ 目录中放置一个模板文件，供 Claude 复制和使用。

你还可以建立 references、scripts、examples 等子目录；这些结构都将帮助 Claude 更高效地工作。

4-避免过度限制 Claude 的灵活性

Claude 通常会尽力遵循你的指令。正因为 Skills 具有很强的可复用性，你需要特别警惕：不要把指令写得过于具体。你需要为 Claude 提供足够的信息，但同时也要为其留出根据具体情境灵活调整的空间。

5-提前规划前置配置

有些 Skill 需要结合用户提供的上下文完成初始化设置。例如，如果你制作的是一个将站会报告发布到 Slack 的 Skill，你可能希望 Claude 先询问：应该发布到哪个 Slack 频道。

一种很好的做法是将这些配置信息存放在 Skill 目录内的 config.json 文件中。这样，如果配置尚未完成，Agent 就可以主动向用户询问必要信息。

如果你希望 Agent 以结构化、多选题的方式向用户提问，可以指示 Claude 使用 AskUserQuestion 工具。

6-Description 字段是写给模型看的

当 Claude Code 启动一个会话时，它会构建一份包含所有可用 Skill 及其描述的清单。Claude 正是通过扫描这份清单来判断：“当前请求是否有对应的 Skill 可以调用？”

这意味着，description 字段并非内容摘要，而是用来描述：这个 Skill 应该在什么情况下被触发。

7-实现记忆与数据存储

有些 Skill 可以通过在自身内部存储数据，形成一种 记忆机制。你可以将数据存储为最简单的“仅追加”文本日志文件或 JSON 文件，也可以复杂到使用 SQLite 数据库。

例如，一个 standup-post Skill 可以维护一个 standups.log 文件，记录它写过的每一条站会报告。这样，当你下一次运行它时，Claude 就能读取历史记录，并判断出相较于昨天发生了哪些变化。

需要注意的是，存放在 Skill 目录中的数据在你升级 Skill 时可能会被删除。因此，这类数据应当存储在一个稳定的目录中。按照原文所述，目前可以使用 ${CLAUDE_PLUGIN_DATA} 作为每个插件独立的稳定数据目录。

8-提供脚本，让 Claude 生成代码

你能赋予 Claude 的最强大工具之一就是代码本身。向 Claude 提供脚本与函数库，可以让它把有限的交互轮次用在“能力组合”上——即决定下一步该做什么——而不是浪费在反复重建样板代码上。

例如，在一个数据科学 Skill 中，你可以准备一套从事件源抓取数据的函数库。这样，当 Claude 需要执行更复杂的分析时，你就可以为其提供一组辅助函数。

随后，Claude 就可以按需动态生成脚本，将这些能力拼接起来，以完成更高级的分析任务，例如回答“周二系统究竟发生了什么？”这类问题。

9-按需启用的钩子（Hooks）

Skills 可以包含一种钩子：它们只会在该 Skill 被调用时才激活，并持续到整个会话结束。对于那些你并不希望一直开启、但在特定场景下又极其有用的强约束钩子，这是一种非常合适的用法。

例如：

• /careful —— 通过 Bash 上的 PreToolUse 匹配器，阻止执行 rm -rf、DROP TABLE、force-push、kubectl delete 等危险操作。只有当你明确知道自己正在操作生产环境时，才会想启用它；如果始终开启，很快就会令人困扰。
• /freeze —— 阻止任何不在指定目录内的编辑或写入操作。这在调试时非常有用，例如“我只是想添加日志，却总是不小心顺手修改了无关代码”。

Skills 的分发策略

Skills 的最大价值之一在于你可以将它们分享给团队中的其他成员。

通常有两种分享 Skills 的方式：

• 直接将 Skills 提交到代码仓库中，放在 ./.claude/skills 目录下
• 将其制作成一个 插件，并建立 Claude Code 的插件市场，让用户能够上传和安装这些插件。

对于仓库数量不多、规模相对较小的团队，直接将 Skills 放入代码仓库通常就足够好用。但每一个直接提交到仓库的 Skill 都会略微增加模型的上下文负担。随着团队规模扩大，建立一个内部插件市场会更合适：它既能帮助你更好地分发 Skills，也能让团队成员自行决定安装哪些技能。

管理插件市场

你应如何决定：哪些 Skills 应该进入市场？团队成员又该如何提交它们？

一种有效的做法并非设立集中式团队统一裁决，而是让真正有价值的 Skill 自然“涌现”。如果你有一个希望他人试用的 Skill，可以先将其上传到 GitHub 的一个沙箱文件夹，然后在 Slack 或其他讨论渠道中分享链接。

当一个 Skill 获得足够的关注（由 Skill 的作者自行判断）后，就可以提交 PR 将其移至插件市场中。

需要提醒的是：制作质量不高或内容重复的 Skills 是很容易的。因此，在正式发布前，确保建立某种 筛选与治理机制 至关重要。

Skills 的组合使用

有时你会希望不同的 Skills 能够互相依赖。例如，你可能有一个负责上传文件的 Skill，又有一个负责先生成 CSV 再调用上传的 Skill。

这种 依赖管理 目前在市场或 Skills 体系中尚未得到原生支持；不过，你可以直接通过名称引用其他 Skills。只要这些 Skills 已经安装，模型就会在需要时调用它们。

衡量 Skills 的效果

为了解一个 Skill 的实际使用表现，可以使用 PreToolUse 钩子，在公司内部记录各个 Skill 的调用情况。

通过这种方式，你就能识别出：哪些 Skills 广受欢迎，哪些 Skills 的触发频率低于预期。

结语

对于 Agents 而言，Skills 是一种极其强大且灵活的工具；但目前仍处于早期探索阶段，所有人都在摸索最佳使用方式。

与其将本文视为一份“终极指南”，不如将其看作一包经过验证、值得借鉴的实战经验。理解 Skills 的最佳方式，就是尽快动手实践，持续实验，然后找到真正适合你团队的工作方法。

内部的大多数 Skill，最初都只是几行说明加上一条常见陷阱。其之所以日益成熟，是因为随着 Claude 不断遇到新的边界情况，人们持续将新的经验补充进去。

希望这些经验能对你的 Claude Code 与 Agent 工作流实践有所帮助。