中文 | English

从构建 Claude Code 中学到的经验：我们如何使用 Skills

这是 Thariq（@trq212）于 2026-03-17 分享的一篇较完整指南，总结了 Anthropic 内部如何使用 skills。

---

背景

Skills 已经成为 Claude Code 中使用最频繁的扩展点之一。它们灵活、容易创建、也容易分发。但正因为这种灵活性，也让人难以判断什么做法效果最好。Thariq 分享了 Anthropic 在内部大规模使用数百个 skills 时积累下来的经验。

---

什么是 Skills？

一个常见误解是，skills “只是 markdown 文件”。但更有意思的地方在于，skill 实际上是一个文件夹，里面可以包含脚本、资源、数据等内容，也就是 agent 可以发现、探索并操作的各种材料。Skill 还有很多配置选项，包括注册动态 hooks。

---

Skills 的类型

在盘点完所有内部 skills 后，团队发现它们大致会聚成 9 类。最好的 skill 往往能清晰落在某一类里；那些让人困惑的 skill，通常横跨了好几类。

---

1/ Library 与 API Reference

这类 skill 解释如何正确使用某个库、CLI 或 SDK。它们既可以针对内部库，也可以针对 Claude Code 容易用错的通用库。通常会附带参考代码片段目录，以及一份在写脚本时需要避开的 gotchas 列表。

示例： billing-lib、internal-platform-cli、frontend-design

---

2/ Product Verification

这类 skill 描述如何测试或验证你的代码是否正常工作。它们通常会与 Playwright、tmux 等外部工具配合使用。Verification skills 对确保 Claude 输出正确非常有帮助，值得让工程师专门花一周把它们打磨到足够好。

示例： signup-flow-driver、checkout-verifier、tmux-cli-driver

---

3/ Data Fetching 与 Analysis

这类 skill 连接你的数据与监控栈。它们可能包含带凭证拉取数据的库、特定 dashboard ID，以及一些常见工作流说明或数据访问方式。

示例： funnel-query、cohort-compare、grafana

---

4/ Business Process 与 Team Automation

这类 skill 把重复流程自动化成一条命令。它们通常只是相对简单的说明，但也可能对其他 skill 或 MCP 有更复杂的依赖。把过往执行结果存进日志文件，有助于模型保持一致性并反思之前的执行过程。

示例： standup-post、create-<ticket-system>-ticket、weekly-recap

---

5/ Code Scaffolding 与 Templates

这类 skill 用于为代码库中的特定功能生成框架样板。你可以把它们与可组合的脚本搭配使用。当脚手架需求包含大量自然语言约束、很难完全靠代码表达时，这类 skill 特别有用。

示例： new-<framework>-workflow、new-migration、create-app

---

6/ Code Quality 与 Review

这类 skill 用来在组织内部强化代码质量并协助 review。它们可以包含确定性脚本或工具，以提高鲁棒性。你可能会希望把这类 skill 自动挂到 hooks 中，或集成进 GitHub Action。

示例： adversarial-review、code-style、testing-practices

---

7/ CI/CD 与 Deployment

这类 skill 帮你在代码库中完成拉取、推送和部署。它们可能会引用其他 skills 来收集所需数据。

示例： babysit-pr、deploy-<service>、cherry-pick-prod

---

8/ Runbooks

这类 skill 从一个症状出发，例如 Slack thread、报警或错误签名，随后完成一段多工具调查流程，并输出结构化报告。

示例： <service>-debugging、oncall-runner、log-correlator

---

9/ Infrastructure Operations

这类 skill 用于执行常规维护和运维流程，其中有些动作具有破坏性，因此更需要 guardrails。它们能让工程师在关键操作中更容易遵循最佳实践。

示例： <resource>-orphans、dependency-management、cost-investigation

---

编写 Skills 的建议

这里整理了 9 条编写高质量 skill 的建议，并补充了分发与度量方式。

---

建议 1：不要写显而易见的内容

Claude Code 对你的代码库已经知道很多，Claude 对编程本身也知道很多，并且自带不少默认偏好。如果你发布的 skill 主要是知识型 skill，就应该把重点放在能把 Claude 从默认思路中“拨出来”的信息上。frontend design skill 就是个好例子，它通过与客户反复迭代，改善 Claude 的设计品味，避免落入 Inter 字体和紫色渐变这类经典默认模式。

---

建议 2：建立 Gotchas 区块

任何 skill 里信号密度最高的内容，往往就是 Gotchas 区块。这些内容应该从 Claude 在使用 skill 时的常见失败点中不断积累出来。理想情况下，你会随着时间持续更新这些 gotchas。

---

建议 3：用文件系统做 Progressive Disclosure

Skill 是一个文件夹，而不只是 markdown 文件。你应该把整个文件系统都当作 context engineering 与 progressive disclosure 的一部分。告诉 Claude 你的 skill 里有哪些文件，它会在恰当的时候读取它们。最简单的形式就是指向其他 markdown 文件，比如把详细函数签名和使用示例拆到 references/api.md 中。你还可以拥有 references、scripts、examples 等目录。

---

建议 4：避免把 Claude 轨道化得太死

Claude 通常会尽量遵循你的指令，而 skill 又具有很强的复用性，所以你需要警惕把它限制得过于具体。给 Claude 它需要的信息，但同时保留对具体情境的适配空间。与其给一步一步的指令，不如给出目标和约束。

---

建议 5：提前想清楚 Setup

有些 skill 需要先拿到用户提供的上下文才能正确工作。一个好的模式是把这些设置信息存进 skill 目录中的 config.json。如果配置还没做好，agent 就可以向用户提问。你还可以明确让 Claude 使用 AskUserQuestion 工具来提结构化、多选式问题。

---

建议 6：Description 字段是写给模型看的

当 Claude Code 启动一个 session 时，它会构建一份可用 skill 列表，并附上每个 skill 的 description。Claude 就是靠扫描这份列表来判断“这个请求有没有对应的 skill”。因此，description 不是给人看的摘要，而是告诉模型什么时候该触发这个 skill。你应该按这个目标来写。

---

建议 7：Memory 与数据存储

有些 skill 可以通过在 skill 目录里存数据来获得某种形式的 memory。存储形式可以是 append-only 文本日志、JSON 文件，复杂时也可以是 SQLite 数据库。需要注意的是，skill 目录中的数据在升级 skill 时可能被删除，因此更稳定的做法是使用 ${CLAUDE_PLUGIN_DATA} 这样的每-plugin 稳定目录来存数据。

---

建议 8：把脚本存进去，并让 Claude 生成组合代码

你能给 Claude 的最强工具之一，其实就是代码本身。给 Claude 提供脚本和库，就能让它把轮次花在组合和决策上，而不是浪费在重建样板代码上。之后 Claude 还可以按需即时生成脚本，把这些能力进一步编排起来，完成更高级的分析。

---

建议 9：按需 Hooks

Skill 可以带有只在 skill 被调用时才启用、并在当前 session 生命周期内持续生效的 hooks。适合用来放那些你不想始终开启、但在某些时候特别有价值的更强硬 hooks。

示例：

• /careful：通过 Bash 的 PreToolUse matcher 阻止 rm -rf、DROP TABLE、force-push、kubectl delete
• /freeze：阻止任何不在指定目录中的 Edit / Write

---

分发 Skills

与团队分享 skills 有两种方式：

• 提交进你的仓库（放在 .claude/skills 下）：适合团队较小、涉及仓库数量相对有限的情况
• 做成 plugin，再建立一个 Claude Code Plugin marketplace，让用户自行上传和安装 plugin

任何被提交进仓库的 skill，都会给模型上下文增加一点负担。随着规模扩大，内部 plugin marketplace 能让你分发 skills，并由团队成员自行决定安装哪些。

---

管理 Marketplace

通常不会有一个中心化团队来决定哪些 skill 可以进入 marketplace。更好的方式是先让有用的 skill 自然生长：把它上传到 GitHub 的 sandbox 目录，再在 Slack 或其他内部论坛中传播。当一个 skill 已经积累足够 traction（判断标准可由 skill owner 自定）后，再通过 PR 把它移入 marketplace。发布前做适度 curate 也很重要，这样可以避免重复 skill 泛滥。

---

组合 Skills

你可能会想要让不同 skill 互相依赖。比如一个上传文件的 skill 负责把文件发出去，另一个生成 CSV 的 skill 则先生成 CSV 再调用上传 skill。当前 marketplace 或 skill 体系还没有原生的依赖管理能力，但你完全可以直接在 skill 中按名字引用其他 skill，只要它们已经安装，模型就会去调用。

---

度量 Skills

如果你想知道一个 skill 实际表现如何，可以使用 PreToolUse hook 记录公司内部的 skill 使用情况。这样你就能找出哪些 skill 很受欢迎，或者哪些 skill 的触发率明显低于预期。

---

结语

对 agent 而言，skills 是极其强大且灵活的工具，但这个领域仍然很早期，大家都还在摸索最好的用法。更适合把这篇内容当作一包“已经被验证有效的实用技巧”，而不是权威定稿。理解 skills 的最好方式，还是尽快开始实践、实验并观察什么对你有效。我们大多数内部 skill 一开始都只有几行文字和一个 gotcha，之所以后来变强，是因为随着 Claude 不断撞到新的边界条件，人们持续往里补充内容。