构建 Claude Code 的经验：我们如何使用 Skill
Thariq (@trq212)
2026-03-18
D
原文
---
title: "构建 Claude Code 的经验：我们如何使用 Skill"
author: "Thariq (@trq212)"
source_url: "https://x.com/trq212/status/2033949937936085378"
published_at: "2026-03-17T16:53:48.000Z"
fetched_at: "2026-07-23T13:33:58Z"
updated_at: "2026-07-23T14:22:57Z"
language: "zh"
review_status: "draft"
---
# 构建 Claude Code 的经验：我们如何使用 Skill
Skill 已经成为 Claude Code 中使用最广泛的扩展点之一。它很灵活，创建起来容易，分发也简单。
但这种灵活性也让人很难判断什么做法最有效。哪些 Skill 值得做？写好一个 Skill 的秘诀是什么？什么时候应该把它分享给别人？
在 Anthropic，我们一直大量使用 Claude Code 的 Skill，目前有数百个正在使用。下面是我们在用 Skill 加快开发速度的过程中总结出的经验。
### 什么是 Skill？
如果你刚接触 Skill，我建议先[阅读我们的文档](https://code.claude.com/docs/en/skills)，或观看我们最新推出的 [Agent Skills 课程](https://anthropic.skilljar.com/introduction-to-agent-skills)。本文默认你已经对 Skill 有所了解。
我们经常听到一种误解，认为 Skill“不过是 Markdown 文件”。但 Skill 最有意思的地方恰恰在于，它不只是文本文件，而是一个文件夹，里面可以放脚本、素材、数据等内容，agent 能够发现、浏览并操作这些内容。
在 Claude Code 中，Skill 还有[丰富的配置选项](https://code.claude.com/docs/en/skills#frontmatter-reference)，包括注册动态 hook。
我们发现，Claude Code 中一些最有意思的 Skill，会创造性地运用这些配置选项和文件夹结构。
## Skill 的类型
我们把所有 Skill 整理归类后，发现它们大多集中在几种反复出现的类型中。好的 Skill 通常能明确归入其中一类；越让人困惑的 Skill，往往越是横跨多个类型。这不是一份权威清单，但可以用来检查组织内部是否还缺少某类 Skill。
### **1. 库与 API 参考资料**
这类 Skill 说明如何正确使用某个库、CLI 或 SDK。它既可以面向内部库，也可以面向 Claude Code 有时难以正确使用的常见库。这些 Skill 通常会带一个存放参考代码片段的文件夹，以及一份避坑清单，提醒 Claude 写脚本时避开常见的坑。
**示例：**
- billing-lib——内部计费库，包括边界情况、常见陷阱等
- internal-platform-cli——列出内部 CLI 封装的每个子命令，并举例说明使用时机
- frontend-design——让 Claude 更好地运用你的设计系统
### **2. 产品验证**
这类 Skill 描述如何测试或验证代码是否正常工作。执行验证时，通常还会配合 Playwright、tmux 等外部工具。
验证类 Skill 对确保 Claude 的产出正确非常有用。甚至值得让一位工程师专门花一周时间，把验证 Skill 打磨到足够好。
可以考虑让 Claude 把运行结果录成视频，让你准确看到它测试了什么；也可以在每一步都用程序化断言检查状态。这些做法通常通过在 Skill 中加入各种脚本来实现。
**示例：**
- signup-flow-driver——在无头浏览器中依次完成注册 → 邮箱验证 → 新手引导，并通过 hook 断言每一步的状态
- checkout-verifier——使用 Stripe 测试卡操作结账界面，确认发票确实进入正确状态
- tmux-cli-driver——用于需要 TTY 的交互式 CLI 测试
### **3. 数据获取与分析**
这类 Skill 会接入组织的数据系统和监控技术栈。其中可能包含使用凭据获取数据的库、特定仪表盘的 ID 等，也会说明常见工作流和数据获取方法。
**示例：**
- funnel-query——说明“要查看注册 → 激活 → 付费，需要关联哪些事件”，并指出哪张表里的 user_id 才是准的
- cohort-compare——比较两个用户群体的留存率或转化率，标出具有统计显著性的差异，并附上分群定义的链接
- grafana——记录数据源 UID、集群名称，以及“问题 → 仪表盘”的对照表
### **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 在组织内部落实代码质量要求，并协助审查代码。为了获得尽可能可靠的结果，其中可以包含确定性脚本或工具。你也可以通过 hook 或 GitHub Action 自动运行这些 Skill。
- adversarial-review——启动一个没有先入之见的 subagent 来挑错，根据意见修复并反复迭代，直到发现的问题只剩细枝末节
- code-style——落实代码风格要求，尤其是 Claude 默认不擅长遵循的风格
- testing-practices——说明如何编写测试以及应该测试什么
### **7. CI/CD 与部署**
这类 Skill 帮助你在代码库中获取、推送和部署代码，也可能引用其他 Skill 来收集数据。
**示例：**
- babysit-pr——监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并
- deploy-\<service\>——构建 → 冒烟测试 → 逐步放量并比较错误率 → 出现回归时自动回滚
- cherry-pick-prod——在独立 worktree 中操作 → cherry-pick → 解决冲突 → 按模板创建 PR
### **8. 操作手册**
这类 Skill 从某个问题迹象入手，例如 Slack 中的一段对话、告警或特定错误特征，然后调用多种工具逐步排查并生成结构化报告。
**示例：**
- \<service\>-debugging——为流量最高的服务建立“症状 → 工具 → 查询模式”的映射
- oncall-runner——获取告警 → 检查常见原因 → 整理调查结果
- log-correlator——输入一个 request ID 后，从所有可能处理过该请求的系统中拉取匹配日志
### **9. 基础设施运维**
这类 Skill 执行日常维护和运维流程，其中一些涉及破坏性操作，因此设置防护措施会很有帮助。它们能让工程师在关键操作中更容易遵循最佳实践。
**示例：**
- \<resource\>-orphans——查找孤立的 pod 或 volume → 发到 Slack → 等待观察期 → 用户确认 → 级联清理
- dependency-management——组织内部的依赖审批流程
- cost-investigation——使用特定 bucket 和查询模式，调查“存储或出口流量账单为什么突然上涨”
## **制作 Skill 的技巧**
决定要做什么 Skill 后，应该怎么编写？下面是我们总结出的一些最佳实践和实用技巧。
我们最近还发布了 [Skill Creator](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)，让大家能更轻松地在 Claude Code 中创建 Skill。
### **不要陈述显而易见的事**
Claude Code 对你的代码库了解很多，Claude 也掌握大量编程知识，并且本来就有许多默认倾向。如果发布的 Skill 主要用于提供知识，应尽量聚焦于那些能让 Claude 跳出惯常思路的信息。
[前端设计 Skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) 就是一个很好的例子。Anthropic 的一位工程师通过与客户反复迭代，逐步提升 Claude 的设计品味，避免 Inter 字体、紫色渐变等常见套路，最终做出了这个 Skill。
### **设置一个 Gotchas（避坑事项）章节**
任何 Skill 里信息价值最高的部分，往往是 Gotchas（避坑事项）章节。这部分应该根据 Claude 使用 Skill 时反复遇到的问题逐步补充。理想情况下，你会持续更新 Skill，把新发现的坑记录下来。
### **利用文件系统与渐进式披露**
就像前面所说，Skill 是一个文件夹，不只是一份 Markdown 文件。你应该把整个文件系统视为上下文工程的一部分，并借它实现渐进式披露。告诉 Claude Skill 中有哪些文件，它会在合适的时候读取。
渐进式披露最简单的形式，是让 Claude 按需读取其他 Markdown 文件。例如，可以把详细的函数签名和使用示例单独放在 references/api.md 中。
再举一个例子：如果最终产物是一份 Markdown 文件，可以在 assets/ 中放一份模板，供 Claude 复制使用。
你可以建立 references、scripts、examples 等文件夹，帮助 Claude 更有效地工作。
### **不要把 Claude 的行动路径规定得太死**
Claude 通常会尽量遵守你的指令。正因为 Skill 可以反复使用，编写指令时更要避免规定得过于具体。给 Claude 提供必要信息，同时保留根据实际情况调整的空间。例如：
### **认真设计初始化流程**
有些 Skill 在使用前需要用户提供上下文。例如，如果正在制作一个把站会更新发到 Slack 的 Skill，可以让 Claude 询问应该发到哪个 Slack 频道。
一种不错的做法，是像上面的例子一样，把这些初始化信息保存在 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 提供脚本和库，它就能把每一轮精力用在组合这些能力、决定下一步做什么，而不必反复重建样板代码。
例如，可以在数据科学 Skill 中放一个函数库，用来从事件源获取数据。为了让 Claude 完成复杂分析，可以为它提供下面这样的辅助函数：
随后，Claude 就能即时生成脚本，组合这些功能，完成更高级的分析，例如回答“星期二发生了什么？”
### **按需启用的 Hook**
Skill 可以包含只在自身被调用时启用、并在会话期间持续生效的 hook。那些规则更严格、不适合一直运行，但在某些时候又非常有用的 hook，就适合采用这种方式。
例如：
- /**careful**——通过 Bash 的 PreToolUse matcher 阻止 rm -rf、DROP TABLE、force-push 和 kubectl delete。只有明确知道自己正在操作生产环境时才需要它——如果一直开着，会把人逼疯
- /**freeze**——阻止对特定目录之外的任何 Edit/Write 操作。很有用
- 调试时：“我想添加日志，但总是不小心‘修复’不相关的
## **分发 Skill**
Skill 的一大好处，就是可以分享给团队里的其他人。
与他人分享 Skill 有两种方式：
- 把 Skill 提交到代码仓库中（放在 ./.claude/skills 下）
- 制作一个 **插件**，并建立 Claude Code 插件市场，让用户上传和安装插件（可在[文档](https://code.claude.com/docs/en/plugin-marketplaces)中了解更多）
对于只使用少量代码仓库的小团队，把 Skill 提交到仓库里就很好用。不过，每个提交进仓库的 Skill 都会占用一点模型上下文。随着规模扩大，内部插件市场可以帮助你分发 Skill，同时让团队成员自行决定安装哪些 Skill。
### **管理插件市场**
如何决定哪些 Skill 应该进入插件市场？大家又该如何提交？
我们没有一个负责集中决策的团队，而是尽量让最有用的 Skill 自然浮现。如果你有一个想让大家试用的 Skill，可以先把它上传到 GitHub 的沙盒目录，再通过 Slack 或其他论坛把链接发给大家。
Skill 得到一定认可后——是否达到这个标准由 Skill 所有者判断——就可以提交 PR，把它移入插件市场。
需要提醒的是，创建质量不佳或功能重复的 Skill 很容易，因此在发布前准备一套筛选把关机制很重要。
### **组合 Skill**
有些 Skill 可能需要相互依赖。例如，可以有一个负责上传文件的 Skill，再有一个生成并上传 CSV 的 Skill。目前，插件市场和 Skill 本身尚未内置这种依赖管理能力，但可以直接按名称引用其他 Skill；只要它们已经安装，模型就会调用。
### **衡量 Skill 的使用情况**
为了了解 Skill 的实际表现，我们使用 PreToolUse hook 记录公司内部的 Skill 使用情况（[示例代码见这里](https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5)）。这样就能找出哪些 Skill 很受欢迎，哪些 Skill 的触发次数低于预期。
## **结语**
Skill 是非常强大而灵活的 agent 工具，但现在仍处于早期阶段，所有人都还在摸索最佳用法。
与其把本文视为一份权威指南，不如把它看成一组经过实践检验的实用技巧。理解 Skill 最好的方法，就是直接动手、不断试验，看看什么适合自己。我们的 Skill 大多起初只有几行内容和一条注意事项；后来 Claude 不断遇到新的边界情况，大家也不断补充，它们才逐渐变得更好。
希望这些内容对你有帮助。有问题随时告诉我。