Claude Code Skills 实践指南：Anthropic 团队内部构建与踩坑经验总结

Skills 已经成为 Claude Code 中高频使用的扩展方式之一。它足够灵活，创建和分发都很方便，但正是这种灵活性，让很多人困惑于如何找到最佳实践：究竟什么样的 Skill 值得投入时间？怎样才算写得好？又该在什么时候分享给团队？

在 Anthropic，我们内部已经构建并使用了数百个活跃的 Skills，积累了不少经验教训。以下是我们在实践中总结的一些核心思路。

什么是 Skills？

如果你还不熟悉 Skills，建议先查阅官方文档。本文默认你已经有了基本了解。

一个常见的误解是，Skills“不就是 Markdown 文件吗”？但实际上，Skill 最有价值的地方恰恰在于它不只是一个文件——它是一个文件夹。这个文件夹里可以包含脚本、资源、数据文件等等，Agent 能够自行发现、浏览并操作这些内容。

在 Claude Code 中，Skills 还支持丰富的配置选项，包括注册动态 Hooks。我们发现，那些最能创造价值的 Skills，往往都巧妙地利用了这些配置和整个文件夹结构。

Skills 的类型

在梳理了我们所有的 Skills 之后，我们发现它们大致可以归为以下几类。定义清晰、归属明确的 Skill 往往效果最好；而那些让人困惑的，通常是试图跨越多类别的。这套分类或许能帮你判断团队里还缺哪一类 Skill。

1. 库和 API 参考

这类 Skill 旨在说明如何正确使用某个特定的库、CLI 工具或 SDK。它可以是内部的，也可以是 Claude Code 有时处理得不太好的通用库。通常包含一个参考代码片段文件夹和一份“常见坑（Gotchas）”清单，用于提醒 Claude 在编写脚本时避开陷阱。

示例：

• billing-lib：说明内部计费库的边界情况和雷区。
• internal-platform-cli：内部 CLI 工具的每个子命令及使用场景示例。
• frontend-design：帮助 Claude 更好地理解和遵循团队的设计规范。

2. 产品验证

用于描述如何测试和验证代码功能是否正常。通常与 Playwright、tmux 等外部工具配合使用。
打磨一个验证类 Skill，对于提升 Claude 的输出质量非常有效。让工程师花一周时间专门优化这类 Skill 通常是值得的。
你可以尝试一些技巧，比如让 Claude 录制测试过程的视频，或在每个步骤强制执行状态断言。这些通常通过在 Skill 中内嵌多个脚本来实现。

示例：

• signup-flow-driver：用无头浏览器跑完“注册→邮箱验证→引导”全流程，并在每一步设置状态断言钩子。
• checkout-verifier：使用 Stripe 测试卡驱动结账 UI，验证发票最终是否正确生成。
• tmux-cli-driver：用于需要 TTY 的交互式 CLI 测试。

3. 数据获取与分析

这类 Skill 用于连接你的数据和监控系统。它可能包含带凭证的数据获取库、特定的 Dashboard ID，以及常见工作流说明和取数方法。

示例：

• funnel-query：说明“注册→激活→付费”漏斗应该关联哪些事件，以及包含规范用户 ID 的核心表。
• cohort-compare：对比两个用户群的留存或转化率，标注统计显著的差异，并链接到用户群定义。
• grafana：包含数据源 UID、集群名称以及“问题→对应 Dashboard”的查找表。关于监控数据可视化的更多探讨，可以参考云栈社区的运维/DevOps板块。

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

旨在将重复性的团队工作流程自动化。这类 Skill 的核心指令可能很简单，但往往会依赖其他 Skill 或 MCP 工具。一个有用的技巧是：将历史执行结果保存为日志文件，这样可以帮助模型保持一致性，并回顾之前的执行情况。

示例：

• standup-post：汇总你的任务追踪系统、GitHub 动态和历史 Slack 记录，生成格式化的站会内容，只展示与上次相比的变化。
• create-<ticket-system>-ticket：强制执行字段 Schema（如合法枚举值、必填项），并自动触发后续流程（如通知审核人、在 Slack 中关联链接）。
• weekly-recap：合并 PR、已关闭的任务以及部署记录，生成格式化的周报。

5. 代码脚手架与模板

用于生成特定功能的框架代码。你可以将它们与可组合的脚本结合使用。当你的脚手架有纯代码无法覆盖的自然语言要求时，这类 Skill 尤其有用。

示例：

• new-<framework>-workflow：生成带有团队自定义注解的新服务、工作流或处理器脚手架。
• new-migration：提供数据库迁移文件的模板及常见坑提示。
• create-app：预装了认证、日志和部署配置的新内部应用脚手架。

6. 代码质量与审查

用于强制执行代码规范或辅助代码评审。可以内嵌确定性的脚本或工具以保证稳定性。这类 Skill 可以作为 Hooks 的一部分自动执行，也可以集成到 GitHub Action 中。

示例：

• adversarial-review：启动一个“全新视角”的子 Agent 进行批评，实施修复，循环迭代直到问题降级为挑剔性意见。
• code-style：执行特定的代码风格规范，尤其是 Claude 默认表现不佳的风格。
• testing-practices：说明如何编写测试用例、应该测试哪些内容。

7. CI/CD 与部署

用于在代码库中获取、推送和部署代码，可能会引用其他 Skill 来收集数据。

示例：

• babysit-pr：监控 PR 状态，自动重试不稳定的 CI，解决合并冲突，开启自动合并。
• deploy-<service>：执行“构建→冒烟测试→灰度发布”，比对错误率，出现回归时自动回滚。
• cherry-pick-prod：在独立工作区执行 cherry-pick→冲突解决→按模板创建 PR 的流程。

8. 运维手册（Runbooks）

接受一个症状输入（如 Slack 消息、告警或错误特征），执行多工具联合排查，并输出结构化的报告。

示例：

• <service>-debugging：针对流量最高的服务，建立“症状→工具→查询模式”的映射。
• oncall-runner：获取告警→检查常见原因→输出排查结论。
• log-correlator：给定一个请求 ID，从所有可能接触过它的系统中拉取匹配日志。

9. 基础设施运维

用于执行常规的维护和操作流程。其中一些操作可能具有破坏性，因此需要内置安全护栏。这类 Skill 让工程师在关键操作中更容易遵循最佳实践。

示例：

• <resource>-orphans：找出孤立的 Pod 或 Volume，发送到 Slack 通知，经过冷静期后由用户确认，再进行级联清理。
• dependency-management：定义团队内部的依赖审批工作流。
• cost-investigation：针对存储或出口费用飙升的情况，给出具体的 Bucket 和查询模式排查路径。

制作 Skills 的技巧

确定了要做什么类型的 Skill 之后，接下来怎么写呢？以下是我们总结的一些最佳实践。

不要陈述显而易见的事

Claude Code 已经对你的代码库有相当了解，Claude 本身对编程也有丰富的默认认知。如果你制作的是一个知识型 Skill，请聚焦于能推动 Claude 跳出惯性思维的信息。
例如，一个前端设计 Skill 的核心价值，可能是提升 Claude 的设计品味，避免它总是使用那些过于泛滥的默认风格（如 Inter 字体、紫色渐变）。

建立“常见坑”专区

任何 Skill 中信息密度最高的部分，就是“常见坑（Gotchas）”。这个部分应该从 Claude 在使用你的 Skill 时反复踩到的真实问题中提炼出来，并随着时间推移持续更新。

善用文件系统与渐进式信息披露

Skill 是一个文件夹，这意味着你可以把整个文件系统看作一种上下文工程和渐进式信息披露的手段。告诉 Claude 你的 Skill 里有哪些文件，它就会在合适的时机去读取它们。
最简单的做法是指向其他 Markdown 文件。例如，你可以把详细的函数签名和使用示例拆分到 references/api.md 里。
另一个例子：如果你的最终输出是一个 Markdown 文件，可以在 assets/ 目录下放一个模板文件供 Claude 复制使用。
你还可以建立包含参考资料、脚本、示例等内容的子文件夹，这能帮助 Claude 更高效地工作。这类组织文档的方法，也是优质技术文档的常见特征。

避免过度约束 Claude

Claude 通常会严格遵循指令，而且 Skills 的可复用性很高，所以要警惕写得太死。给 Claude 它需要的信息，同时留给它足够的灵活性来适应不同情境。简单来说：给它方向，而不是给它剧本。

想清楚初始化设置

有些 Skill 可能需要用户提供初始上下文。例如，一个把站会内容发到 Slack 的 Skill，可能需要先询问用户要发到哪个频道。
一个好的模式是：将这些配置信息存储在 Skill 目录下的 config.json 文件中。如果配置尚未完成，Agent 就会主动向用户询问。
如果你想让 Agent 以结构化的多选形式提问，可以指示 Claude 使用 AskUserQuestion 工具。

Description 字段是写给模型的

Claude Code 启动时，会为所有可用 Skill 建立一份包含描述的清单。Claude 正是通过扫描这份清单来判断“有没有适合当前请求的 Skill”。
因此，描述字段不是摘要，而是触发条件的说明——明确告诉模型什么时候应该调用这个 Skill。

记忆与数据存储

部分 Skill 可以通过在内部存储数据来实现一种“记忆”能力。从最简单的追加写入日志或 JSON 文件，到使用 SQLite 数据库，都可以。
例如，standup-post Skill 可以维护一个 standups.log 文件，记录每次发布的内容。下次运行时，Claude 读取这份历史，就能知道自上次以来发生了哪些变化。
需要注意：存储在 Skill 目录中的数据，在升级 Skill 时可能会被删除。建议将需要持久化的数据存放在稳定目录中——目前提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件专属的稳定存储目录。

存放脚本，让 Claude 生成代码

你能给 Claude 的最强工具之一，就是代码本身。提供现成的脚本和库，能让 Claude 把精力集中在组合与决策上，而不是每次都从零开始写样板代码。
例如，在一个数据科学 Skill 中，你可以放入一个从事件源拉取数据的函数库。为了让 Claude 能进行复杂分析，你可以提供一组辅助函数，让它能够动态生成脚本来组合这些功能，从而回答诸如“上周二发生了什么？”这样的问题。

按需 Hooks

Skills 可以包含仅在调用该 Skill 时激活、并持续整个会话的 Hooks。这对于那些你不想一直开启、但在特定场景下非常有用的行为来说非常适合。

示例：

• /careful：通过 PreToolUse 匹配器屏蔽 rm -rf、DROP TABLE、强制推送、kubectl delete 等危险命令。你可能只想在操作生产环境时才启用它——如果一直开着会干扰日常工作。
• /freeze：屏蔽任何不在指定目录中的编辑/写入操作。在调试时很有用，可以防止“我只想加日志，却总是不小心顺手修复了不相关的问题”。

分发 Skills

Skills 的一大优势就是可以分享给整个团队。分享主要有两种方式：

• 将 Skills 提交到你的代码仓库（放在 ./.claude/skills 目录下）。
• 搭建一个插件市场，让用户上传和安装插件（详见官方文档）。

对于代码库不多的小团队，把 Skills 提交到仓库效果很好。但每增加一个 Skill，也会略微增加模型的上下文负载。随着规模扩大，内部插件市场可以帮助你更灵活地分发 Skills，让团队成员自行决定安装哪些。

管理插件市场

哪些 Skills 可以进入市场？怎么提交？我们没有设立集中的审核团队，而是让有用的 Skills 自然涌现：如果你有一个想让大家都试试的 Skill，可以先上传到 GitHub 的沙盒目录，然后在 Slack 或其他论坛里告诉大家。
一旦某个 Skill 获得了足够的认可（由 Skill 作者自己判断），就可以提 PR 将它移入正式市场。
需要注意的是，创建质量差或功能重复的 Skill 非常容易，所以在正式发布前，确保有某种形式的筛选机制很重要。

组合 Skills

你可能希望让 Skills 之间能够互相依赖。例如，你有一个文件上传 Skill，还有一个生成 CSV 并上传的 Skill。这种依赖管理目前还没有被内置到市场或 Skill 框架中，但你可以直接在 Skill 中按名称引用其他 Skill，模型会在它们已安装的情况下自动调用。

衡量 Skills 的效果

为了了解一个 Skill 的使用情况，我们使用了一个 PreToolUse Hook 来记录公司内部的 Skill 调用日志（示例代码见官方文档）。这样我们就能找出哪些 Skill 很受欢迎，哪些 Skill 的触发率低于预期。

结语

Skills 是 Agent 工作流中极其强大且高度灵活的工具——但我们都还处于摸索阶段，没有人真正“搞定”了它。
把本文看作一袋有用的实践技巧，而不是一份权威指南。理解 Skills 最好的方式，就是动手去做、去实验、去观察哪些方法对你和你的团队真正有效。我们自己的大多数 Skills，一开始也不过是几行文字加上一条“常见坑”，之后随着 Claude 不断遇到新问题，大家持续往里面添加内容，才慢慢变得成熟。

你是否也有构建 Claude Code Skill 的独特经验或踩坑故事？欢迎在云栈社区的技术论坛板块分享和讨论。

原文来源：https://x.com/trq212/status/2033949937936085378