Claude Code Skills 全解：九类用法与九条经验

原创 Thariq 2026-07-20 16:27 江苏

Anthropic 内部几百个 Skill，最值钱的是踩坑记录

今年 3 月，Claude Code 团队成员 Thariq 在 X 上发布了长文《Lessons from Building Claude Code: How We Use Skills》。他在文中提到，Anthropic 内部已经有数百个 Skill 处于活跃使用状态。

这篇文章没有停在SKILL.md的写法上。九类内部用法之外，Thariq 还讲了 Gotchas、渐进式披露、脚本、动态 Hook、团队分发和使用统计。对于正在把 Claude Code 从个人工具推向团队工作流的人，这些细节比再抄一份模板更有参考价值，以下是全文翻译。

---

Skill 已经成为 Claude Code 中使用最广泛的扩展点之一。它很灵活，制作容易，分发也简单。

但灵活也会带来选择困难：什么类型的 Skill 值得做？写好一个 Skill 的秘诀是什么？什么时候应该把它分享给其他人？我们在 Anthropic 内部广泛使用 Claude Code Skills，目前有数百个处于活跃使用状态。下面是我们利用 Skills 加速开发过程中总结出的经验。

Skill 是什么？

如果你刚接触 Skills，我建议先阅读官方文档，或者观看 Skilljar 上最新的 Agent Skills 课程。下文默认你已经对 Skills 有一些基本了解。

我们经常听到一种误解：Skill“就是一个 Markdown 文件”。这种说法忽略了 Skill 最关键的能力。它实际是一个文件夹，可以放入脚本、资产、数据等内容，Agent 能够发现、查看并操作这些文件。在 Claude Code 中，Skill 还有很多配置选项，包括注册动态 Hook。我们见过的一些很有创造力的 Skill，正是把这些配置能力和文件夹结构组合了起来。

Skill 的类型

我们清点了内部所有 Skill，发现它们大多会聚集到几个反复出现的类别中。好用的 Skill 通常能清楚归入一类；让人困惑的 Skill 往往横跨好几类。下面并非最终或完整清单，但它能帮助你检查自己的组织里是否缺了某一类能力。

1. Library & API Reference，库与 API 参考。这类 Skill 说明怎样正确使用某个库、CLI 或 SDK，既可以面向内部库，也可以面向 Claude Code 偶尔难以正确使用的通用库。它们通常会附带一个参考代码片段目录，以及一份 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，在无头浏览器中跑完注册、邮件验证和新手引导，并用 Hook 断言每一步状态；checkout-verifier，用 Stripe 测试卡操作结账界面，再确认发票确实进入正确状态；tmux-cli-driver，测试必须运行在真实 TTY 中的交互式 CLI。

3. Data Fetching & Analysis，数据获取与分析。这类 Skill 连接团队的数据与监控栈。它可以包含带凭据的数据获取库、特定仪表盘 ID，以及常见工作流和取数方式的说明。例子包括：funnel-query，回答“要看注册、激活到付费的漏斗，应该连接哪些事件”，并指出真正保存规范 user_id 的表；cohort-compare，比较两个群组的留存或转化，标出有统计显著性的差异，并链接到分群定义；grafana，记录数据源 UID、集群名称，以及从问题到仪表盘的查询表。

4. Business Process & Team Automation，业务流程与团队自动化。这类 Skill 把重复工作压缩成一条命令。说明本身通常不复杂，但可能依赖其他 Skill 或 MCP。把历次结果保存在日志文件中，可以帮助模型保持一致，并回顾此前每一次工作流执行。例子包括：standup-post，汇总工单系统、GitHub 活动和上一份 Slack 站会，只输出新增变化并整理成站会格式；create--ticket，强制执行字段 Schema，包括合法枚举值和必填项，再完成创建后的流程，例如提醒 Reviewer、把链接发到 Slack；weekly-recap，汇总已合并 PR、已关闭工单和部署记录，生成格式化周报。

5. Code Scaffolding & Templates，代码脚手架与模板。这类 Skill 为代码库中的特定功能生成框架样板，也可以和可组合脚本一起使用。当脚手架包含无法完全用代码表达的自然语言要求时，它尤其有用。例子包括：new--workflow，按团队注解约定创建新的服务、工作流或 Handler；new-migration，提供迁移文件模板和常见 Gotchas；create-app，生成已经接好认证、日志和部署配置的内部应用。

6. Code Quality & Review，代码质量与审查。这类 Skill 用来落实组织内部的代码质量要求并辅助 Review。为了获得更稳健的结果，可以加入确定性脚本或工具，也可以通过 Hook 或 GitHub Action 自动运行。例子包括：adversarial-review，启动一个用全新视角审查代码的 Subagent，修复发现的问题并持续迭代，直到剩下的都只是细枝末节；code-style，执行代码风格要求，尤其关注 Claude 默认不擅长遵守的部分；testing-practices，说明测试该怎么写、应该测试什么。

7. CI/CD & Deployment，持续集成、交付与部署。这类 Skill 帮助你在代码库中拉取、推送和部署代码，也可能引用其他 Skill 来收集数据。例子包括：babysit-pr，持续监控一个 PR，重试偶发失败的 CI、解决合并冲突并开启自动合并；deploy-，依次完成构建、冒烟测试、逐步放量和错误率比较，发现回归后自动回滚；cherry-pick-prod，创建隔离 Worktree、执行 Cherry-pick、解决冲突，再按模板创建 PR。

8. Runbooks，运行手册。这类 Skill 从一个症状出发，例如 Slack 线程、告警或错误签名，带着 Agent 使用多个工具完成调查，最后生成结构化报告。例子包括：-debugging，把高流量服务的症状映射到工具和查询模式；oncall-runner，拉取告警、检查常见故障点并整理调查结果；log-correlator，根据一个请求 ID，从所有可能处理过该请求的系统中找出对应日志。

9. Infrastructure Operations，基础设施运维。这类 Skill 处理日常维护和运维流程，其中一些操作具有破坏性，因此很适合加入护栏。它能帮助工程师在关键操作中遵循最佳实践。例子包括：-orphans，查找孤立 Pod 或 Volume、把结果发到 Slack、等待观察期、由用户确认后再执行级联清理；dependency-management，落实组织内部的依赖审批流程；cost-investigation，根据具体 Bucket 和查询方式调查“为什么存储或出口流量账单突然上涨”。

制作 Skill 的技巧

决定要做哪一种 Skill 之后，接下来就是怎样写。下面是我们实践中发现的一些有效方法、技巧和经验。我们最近也发布了 Skill Creator，让 Claude Code 中创建 Skill 的过程更容易。

不要陈述显而易见的内容。Claude Code 已经很了解你的代码库，Claude 对编程也有大量知识和默认倾向。如果你发布的 Skill 主要用于补充知识，请优先写那些能把 Claude 推出惯常思路的信息。frontend-design Skill 就是一个很好的例子：Anthropic 的一名工程师通过持续和客户迭代来改善 Claude 的设计品位，并让它避开 Inter 字体、紫色渐变这类常见套路。

建立 Gotchas 小节。一个 Skill 中信号最强的内容，通常就是 Gotchas。这个小节应该从 Claude 使用该 Skill 时经常遇到的失败点逐步积累。理想情况下，随着使用时间增长，你会持续更新 Skill，把新出现的坑补进去。

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

前面提过，Skill 是一个文件夹，不能只看成一份 Markdown。整个文件系统都可以视作上下文工程和渐进式披露的一部分。告诉 Claude 这个 Skill 里有哪些文件，它就会在合适的时候读取它们。

最简单的渐进式披露，是指向其他 Markdown 文件供 Claude 按需使用。例如，可以把详细函数签名和使用示例拆到references/api.md。如果最终产物是一份 Markdown，也可以在assets/中放入模板，让 Claude 复制使用。Skill 目录还可以包含 references、scripts、examples 等文件夹，帮助 Claude 更有效地完成工作。

不要把 Claude 限死

Claude 通常会尽量遵循你的指令。由于 Skill 会被重复使用，编写指令时要谨慎，避免规定得过细。给 Claude 完成任务所需的信息，同时保留根据现场情况调整的空间。

提前想清楚初始化配置。有些 Skill 需要先向用户获取上下文。例如，一个负责把站会内容发到 Slack 的 Skill，可能需要先询问应该发到哪个频道。一种好做法，是像示例中那样把配置保存在 Skill 目录的config.json。如果配置尚未完成，Agent 再向用户提问。需要让 Agent 提出结构化的多选问题时，可以明确要求 Claude 使用 AskUserQuestion 工具。

Description 字段是写给模型看的。Claude Code 启动会话时，会根据所有可用 Skill 的 description 建立一份列表。Claude 就靠这份列表判断“这个请求有没有对应的 Skill”。因此，description 的主要任务是说明什么时候应该触发这个 Skill，并非写一段供人阅读的项目摘要。

记忆与数据存储。有些 Skill 可以把数据保存在自身目录中，从而形成一种记忆。实现方式可以很简单，例如只追加不修改的文本日志或 JSON 文件；也可以复杂到使用 SQLite 数据库。例如，standup-post Skill 可以用standups.log保存发过的每一条站会内容。下次运行时，Claude 读取自己的历史记录，就能判断和昨天相比发生了什么变化。Skill 升级时，保存在 Skill 目录中的数据可能会被删除，因此应该写入稳定目录。目前我们为每个插件提供${CLAUDE_PLUGIN_DATA}，作为持久保存数据的位置。

保存脚本，让 Claude 生成代码

代码是你能提供给 Claude 的强力工具之一。给 Claude 准备脚本和函数库，它就可以把推理轮次用在组合能力、决定下一步，而无需每次重新拼装样板代码。

例如，数据科学 Skill 可以提供一组从事件源取数的函数。Claude 随后可以临时生成脚本，把这些辅助函数组合起来，完成更复杂的分析，并回答“周二发生了什么？”这样的问题。

按需启用 Hook。Skill 可以注册只在被调用时激活、并持续到当前会话结束的 Hook。它适合那些不应该一直运行，但在某些场景非常有用的强约束。例如：/careful通过 Bash 的 PreToolUse Matcher 阻止rm -rf、DROP TABLE、强制推送和kubectl delete，只在确定要操作生产环境时启用，否则一直开着会让人抓狂；/freeze阻止对指定目录之外的任何 Edit 或 Write，适合“我只想加日志，却总是不小心顺手改掉无关内容”的调试场景。

分发 Skills

Skill 的一大好处，是可以分享给团队中的其他人。分享主要有两种方式：把 Skill 提交到代码仓库的./.claude/skills目录；或者把它制作成插件，并建立一个 Claude Code Plugin Marketplace，让用户上传和安装插件。

如果小团队只在少数几个仓库中工作，直接把 Skill 提交进仓库就很好用。但每个进入仓库的 Skill 都会占用一点模型上下文。团队规模扩大后，内部 Plugin Marketplace 可以集中分发 Skill，同时让每个人自行决定安装哪些。

管理 Marketplace。哪些 Skill 应该进入 Marketplace？提交方式应该怎样设计？我们没有设立一个集中决策的团队，而是让真正有用的 Skill 自然浮现。如果你想让别人试用自己的 Skill，可以先把它上传到 GitHub 的 Sandbox 目录，再通过 Slack 或其他论坛邀请大家使用。Skill 获得足够使用量之后，具体标准由 Skill Owner 判断，就可以提交 PR，把它移入 Marketplace。需要注意，制作出质量差或功能重复的 Skill 很容易，因此正式发布前必须有某种筛选机制。

组合 Skills。有些 Skill 会依赖其他 Skill。例如，一个文件上传 Skill 负责上传文件，另一个 CSV 生成 Skill 负责创建 CSV 并调用上传能力。Marketplace 和 Skill 目前没有内建这种依赖管理，但你可以直接在说明中引用其他 Skill 的名称；只要它们已经安装，模型就会调用。

度量 Skills。为了了解一个 Skill 表现如何，我们使用 PreToolUse Hook 记录公司内部的 Skill 使用情况。这样就能找出哪些 Skill 很受欢迎，以及哪些 Skill 的触发次数低于预期。

结语

Skill 是非常强大、灵活的 Agent 工具，但这个领域仍处在早期，大家都还在探索怎样把它用好。

与其把本文当成一份权威指南，不如把它看成一包已经在实践中奏效的经验。理解 Skill 的最佳方式，是先做起来、不断实验，再观察什么对自己有效。我们的大多数 Skill 起步时只有几行文字和一个 Gotcha；后来 Claude 遇到新的边缘情况，使用者不断把经验补进去，它们才一点点变好。

希望这些内容对你有帮助。有任何问题，欢迎告诉我。

参考链接

原文《Lessons from Building Claude Code: How We Use Skills》：https://x.com/trq212/status/2033949937936085378
作者 Thariq：https://x.com/trq212

Claude Code Skills 文档：https://code.claude.com/docs/en/skills
Agent Skills 课程：https://anthropic.skilljar.com/introduction-to-agent-skills
Skills Frontmatter Reference：https://code.claude.com/docs/en/skills#frontmatter-reference

Skill Creator：https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills
Frontend Design Skill：https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
Plugin Marketplace 文档：https://code.claude.com/docs/en/plugin-marketplaces
Skill 使用统计示例：https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5

进技术交流群请添加AINLP小助手微信（id: ainlp2)

请备注具体方向+所用到的相关技术点

关于AINLP

AINLP 是一个有趣有AI的自然语言处理社区，专注于 AI、NLP、机器学习、深度学习、推荐算法等相关技术的分享，主题包括LLM、预训练模型、自动生成、文本摘要、智能问答、聊天机器人、机器翻译、知识图谱、推荐系统、计算广告、招聘信息、求职经验分享等，欢迎关注！加技术交流群请添加AINLP小助手微信(id：ainlp2)，备注工作/研究方向+加群目的。