↑阅读之前记得关注+星标⭐️，😄，每天才能第一时间接收到更新

这篇文章可能是26年初最有价值的一篇skill实践总结。

来自 Claude code 团队成员Thariq老哥，他们在公司内部已经积累了数百个 Skills（技能插件）在日常开发中高频使用，踩过无数坑，也摸索出了一套行之有效的方法论。

以下原文中文版奉上：

构建 Claude Code 的那些经验：我们是如何使用 Skills 的

作者：Thariq

Skills 已经成为 Claude Code 中使用最频繁的扩展点之一。它灵活、易于创建、也方便分发。

但正是这种灵活性，让人很难知道什么才是最佳实践：什么类型的 Skill 值得做？怎么写一个好的 Skill？什么时候该把它分享给团队？

在 Anthropic，我们自己也在大量使用 Skills，内部有数百个处于活跃状态。以下是我们在实践中总结出的经验。

什么是 Skills？

如果你对 Skills 还不熟悉，建议先读一下官方文档，或者去 Skilljar 上看我们最新发布的 Agent Skills 课程。本文默认你已经对 Skills 有基本了解。

我们听到一个常见误解：Skills "不就是 Markdown 文件吗"？但 Skills 最有意思的地方恰恰在于它不只是文本文件——它是一个文件夹，可以包含脚本、资源文件、数据等，Agent 可以自行发现、浏览和操作这些内容。

在 Claude Code 中，Skills 还支持丰富的配置选项，包括注册动态 Hooks（钩子）。我们发现，那些最有价值的 Skills，往往正是创造性地利用了这些配置项和文件夹结构。

Skills 的类型

在梳理我们所有的 Skills 之后，我们发现它们大致可以归纳为以下几类。最好的 Skills 往往清晰地属于某一类；而令人困惑的 Skills，通常是跨了好几类。这不是一份权威定义，但可以帮助你判断自己的团队是否有哪类 Skill 还缺失。

1. 库和 API 参考

用于说明如何正确使用某个库、CLI 工具或 SDK。既可以是内部库，也可以是 Claude Code 有时候处理不好的通用库。这类 Skill 通常包含一个参考代码片段文件夹，以及一份"常见坑"清单，提醒 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"查找表

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

用于将重复性工作流程自动化为一条指令。这类 Skill 的核心指令通常比较简单，但可能依赖其他 Skill 或 MCP 工具。对于这类 Skill，将历史结果保存为日志文件，可以帮助模型保持一致性，并回顾之前的执行结果。

示例：

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

5. 代码脚手架与模板

用于生成特定功能的框架代码。你可以把这类 Skill 与可组合的脚本结合使用。当你的脚手架有纯代码无法覆盖的自然语言要求时，这类 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 之后，该怎么写？以下是我们总结的最佳实践。

（我们最近还发布了 Skill Creator，让在 Claude Code 中创建 Skills 变得更简单。）

不要陈述显而易见的事

Claude Code 已经对你的代码库了解很多，Claude 本身对编程也有丰富的默认认知。如果你做的是一个以知识为主的 Skill，请聚焦于能推动 Claude 跳出惯性思维的信息。

前端设计 Skill 是个很好的例子——它由 Anthropic 的一位工程师通过与用户反复迭代打磨而成，核心是提升 Claude 的设计品味，避免使用 Inter 字体、紫色渐变等泛滥的默认风格。

建立"常见坑"专区

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

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

前面说过，Skill 是一个文件夹，不只是一个 Markdown 文件。你应该把整个文件系统看作一种上下文工程和渐进式信息披露的手段——告诉 Claude 你的 Skill 里有哪些文件，它就会在合适的时机去读取它们。

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

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

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

避免过度约束 Claude

Claude 通常会严格遵循你的指令，而且 Skills 的可复用性很高，所以要警惕写得太死。给 Claude 它需要的信息，同时留给它足够的灵活性来适应不同情境。举个例子：

给它方向，而不是给它剧本。

想清楚初始化设置

有些 Skill 可能需要用户提供初始上下文。例如，一个把站会内容发到 Slack 的 Skill，可能需要 Claude 先询问用户要发到哪个频道。

一个好的模式是：将这些配置信息存储在 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：屏蔽任何不在指定目录中的编辑/写入操作。调试时很有用："我只想加日志，但我老是不小心顺手修复了不相关的问题"