Claude Code 团队如何使用 Skill：把经验写进 Agent 的工作现场
你让 AI 写一段脚本，它能完成。你让它接手一个团队里的真实工作流，它很快会撞上那些文档里没有写清楚的细节：内部 CLI 的坑、监控面板的 ID、测试环境的假阳性、发布流程里的人工确认、某个字段在两个系统里叫法不同。
Claude Code 团队把这些细节放进 Skill。
Anthropic 在《Lessons from building Claude Code: How we use skills》里分享了他们的内部经验：Claude Code 团队已经在 Anthropic 内部大量使用 Skill，并有数百个 Skill 处于活跃使用状态。工程师把团队已经知道的做事方式放进 Skill，让 Agent 在合适的时候调用。
Skill 不是“一个 Markdown 文件”
很多人第一次看到 Skill，会把它理解成一份 SKILL.md。Anthropic 明确纠正了这个误解：Skill 是一个文件夹，里面可以包含说明、脚本、资产、数据和其他资源。Agent 发现它、读取它、按需探索它，再用它把任务做得更准、更快。
这点很关键。单个 Markdown 只能给模型一段上下文；文件夹可以承载一套工作环境。比如：
references/api.md存放 API 签名和示例。assets/template.md提供固定输出模板。scripts/verify.js执行可重复的校验。config.json保存团队或用户的配置。- 日志文件记录上次执行结果，帮助 Agent 比较变化。
Claude Code 里的 Skill 还可以注册动态 hooks。Anthropic 提到，一些最有效的 Skill 会用好这些配置能力和文件结构，避免停留在一段长说明上。
flowchart LR
A[用户任务] --> B[Claude Code 发现相关 Skill]
B --> C[读取 SKILL.md]
C --> D{是否需要更多上下文}
D -->|需要| E[读取 references / assets / scripts / config]
D -->|不需要| F[直接执行]
E --> F
F --> G[验证结果并产出交付物]
Anthropic 内部的九类 Skill
Claude Code 团队梳理了 Anthropic 内部 Skill 后，发现它们大致落在九类里。这个分类很实用，因为它帮你判断一个 Skill 到底该解决什么问题。Anthropic 也提醒：最好的 Skill 往往能清楚落在某一类里；一个 Skill 如果横跨太多类别，Agent 反而容易困惑。
1. Library and API reference
这类 Skill 教 Claude 正确使用某个库、CLI 或 SDK。它适合放内部库的边界条件、常见坑、代码片段和调用示例。
比如内部 billing library 里哪些字段不能乱用，内部平台 CLI 的子命令该在什么场景执行，开发环境的 egress gateway 该如何排查连接失败。这些知识通常散在代码、Slack 和工程师脑子里。Skill 把它们收进一个可调用的位置。
2. Product verification
Anthropic 说，验证类 Skill 对 Claude 输出质量的影响最可衡量。这类 Skill 会告诉 Claude 如何测试代码是否真的可用，常和 Playwright、tmux 或其他外部工具配合。
一个注册流程验证 Skill 可以驱动浏览器跑完注册、邮件验证和 onboarding，并在每一步断言状态。一个 checkout verifier 可以使用 Stripe 测试卡完成支付流程，再检查发票状态是否正确。对于交互式 CLI，tmux 这类工具能提供真实 TTY。
这类 Skill 的价值在于：它把“看起来能跑”变成“有证据地跑过”。
3. Data fetching and analysis
数据分析类 Skill 连接数据仓库、监控系统和仪表盘。它可以告诉 Claude 该 join 哪些事件、哪个表里有 canonical user_id、Grafana datasource UID 是什么、Datadog 里的字段命名规则是什么。
没有这些信息，Agent 容易写出形式正确但业务错误的查询。有了 Skill，它能从团队认可的数据路径开始分析。
4. Business process and team automation
这类 Skill 把重复的团队流程压成一个命令。比如生成 standup、创建工单、写周报。
Anthropic 特别提到，保存历史执行结果有助于模型保持一致。一个 standup Skill 如果记录每次发过的内容，下次执行时就能只写增量，而不是重复昨天的进展。
5. Code scaffolding and templates
脚手架类 Skill 生成符合团队规范的代码骨架。它适合处理那些纯代码生成器覆盖不了的自然语言要求，比如新服务需要带上认证、日志、部署配置和注释约定。
如果一个迁移文件经常因为命名、回滚策略或边界条件出错，把模板和 gotchas 放进 Skill，比每次在 PR 里纠正更省力。
6. Code quality and review
代码质量类 Skill 帮 Claude 做审查、执行规则或调用确定性工具。Anthropic 举的例子包括 adversarial review、code style 和 testing practices。
这类 Skill 可以由 Claude 主动调用，也可以挂在 hooks 或 GitHub Action 中。越接近质量门禁，越应该把规则写清楚，并尽量用脚本兜底。
7. CI/CD and deployment
发布类 Skill 帮 Claude 获取代码、处理 PR、观察 CI、解决冲突、执行发布和回滚。它通常需要组合其他 Skill，比如先收集指标，再决定是否继续 rollout。
这类任务带有真实风险。Skill 不该只写“执行部署”，还要写清楚 smoke test、错误率对比、灰度策略和回滚条件。
8. Runbooks
Runbook 类 Skill 从症状出发，带 Claude 做多工具调查，并产出结构化报告。症状可以来自 Slack 线程、告警或错误签名。
好的 runbook 不会让 Claude 漫无目的地查日志。它会建立“症状到工具，再到查询模式”的路径：收到某服务告警后先看哪几个指标，拿到 request ID 后去哪些系统查关联日志，结论该如何写给值班同学。
9. Infrastructure operations
基础设施运维类 Skill 处理例行维护和带风险的操作。比如查找孤儿资源、管理依赖审批、分析存储或 egress 账单上涨。
Anthropic 特别强调 guardrails。涉及删除资源、修改生产环境、force push 或执行数据库危险操作时，Skill 要通过确认步骤、hooks 或脚本限制降低误操作概率。
好 Skill 写的是“额外知识”，不是常识
Anthropic 给出的第一条写法建议很直接：不要写显而易见的东西。Claude 本来就会写代码，也能读代码库。一个 Skill 如果只重复“先理解需求，再修改代码，再运行测试”，它只会增加上下文负担。
Skill 应该写 Claude 默认不知道、但团队成员知道的东西。
原文给了几个典型例子：subscriptions 表是 append-only，要取最高 version 的行，而不是最新 created_at；API gateway 里的 @request_id 和 billing service 里的 trace_id 指的是同一个值；staging 返回 200 不代表 Stripe webhook 真处理成功，要看 payment_events。
这些就是高价值信息。它们很小，但能防止 Agent 走错路。
Gotchas 是 Skill 的核心资产
Anthropic 认为，任何 Skill 里信号最高的部分都是 Gotchas。原因也简单：Gotchas 来自真实失败。
你不需要一次写出完美 Skill。更好的方式是先写几行说明和一个常见坑，然后在 Claude 每次踩到新边界时补进去。几周之后，这个 Skill 会变成团队经验的沉淀，而不是一次性文档。
可以把 Gotchas 写成短句：
- 这个表不能按创建时间取最新记录，要按业务版本号取最大值。
- 这个环境的健康检查会误报成功，需要查事件表。
- 这个 CLI 子命令默认指向 staging，生产环境必须显式传
--prod。
这类句子不漂亮，但有用。
用文件系统做渐进披露
Skill 不应该把所有内容塞进一个超长 SKILL.md。Anthropic 推荐用文件系统做 progressive disclosure：SKILL.md 告诉 Claude 有哪些参考文件，Claude 在需要时再读。
这能同时解决两个问题。第一，启动时上下文更轻。第二，Agent 能按任务取用材料，而不是被一堆无关细节干扰。
一个数据分析 Skill 可以这样组织：
| |
当用户问“周二发生了什么”，Claude 可以先读 SKILL.md，再调用脚本取数据，必要时查看 cohorts 定义，然后套用报告模板。模型把精力放在判断和组合上，少花时间临时重写样板代码。
不要把 Claude 卡死在流程里
Skill 需要给方向，但不能把 Claude railroad 到只会按一个剧本执行。Anthropic 的建议是：给 Claude 足够信息，同时保留适应现场的空间。
这在团队自动化里很常见。比如一个 standup-post Skill 需要 Slack channel。如果配置里没有 channel，Skill 可以让 Claude 提问；如果已经配置好，就直接执行。配置可以放在 config.json 里，Agent 先检查配置，再决定是否需要用户补充信息。
对于可选项明确的问题，Anthropic 还提到可以让 Claude 使用 AskUserQuestion 这类结构化提问工具。关键不在工具本身，而在 Skill 把“什么信息必须提前确定”写清楚。
description 写给模型看，不是写给人看
Claude Code 启动时会列出可用 Skill 及其 description。Claude 依靠这段描述判断某个请求该不该触发该 Skill。
所以 description 要写触发条件，而不是写简介或营销文案。
如果团队里有一个 babysit-pr Skill，description 里就应该包含 “babysit” 这类用户会说出口的词。模型扫描技能列表时，能把用户请求和 Skill 对上。
给 Skill 一点记忆
有些 Skill 可以保存自己的历史。Anthropic 提到，可以用 append-only 文本日志、JSON 文件，甚至 SQLite 数据库存储数据。Claude Code 还提供 ${CLAUDE_PLUGIN_DATA} 作为稳定的数据目录，用于 Skill 持久化。
这类记忆适合增量任务。standup-post 记录每天发过什么，下次就能判断新增进展；PR review Skill 记录上次审过哪些点，下次可以避免重复劳动。
注意，记忆不是让 Agent 自作主张。它只是让 Agent 在下一次执行时拥有可核对的历史。
把代码放进 Skill
Anthropic 说，代码是你能交给 Claude 的最强工具之一。脚本和库能让 Claude 少花时间重建样板，多花时间判断下一步做什么。
这也是 Skill 和普通提示词的分水岭。提示词只能要求模型“按规则做”；Skill 可以提供 verify、fetch、deploy、compare 这类可执行能力。对于需要稳定复现的工作，脚本比自然语言可靠。
尤其是验证、数据抓取、发布和运维任务，应该尽量把关键步骤脚本化。Claude 负责选择和组合，脚本负责执行和断言。
按需 hooks 适合高约束场景
Claude Code 的 Skill 可以包含只在 Skill 被调用时生效的 hooks，并且只持续当前会话。Anthropic 用两个例子解释了这个能力：
/careful：通过 PreToolUse matcher 阻止rm -rf、DROP TABLE、force push、kubectl delete等危险操作。/freeze：限制 Edit/Write 只能发生在特定目录，适合调试时只加日志，不碰其他代码。
这类 hooks 不适合全局常开。它们适合在你知道任务风险较高时打开，让 Agent 在更窄的边界内工作。
分发：小团队放仓库，大团队做市场
Skill 的一个核心价值是共享。Anthropic 提到两种分发方式：
- 把 Skill 放进仓库里的
./.claude/skills。 - 制作 plugin，通过 Claude Code Plugin marketplace 分发。
小团队、少量仓库，直接把 Skill 放进 repo 很方便。规模变大后，每个仓库内置的 Skill 都会增加模型上下文。内部 marketplace 更适合大团队：使用者按需安装，Skill 可以带 setup flow，团队也能观察哪些 Skill 真有用。
Anthropic 内部没有让一个中心团队决定所有 Skill 是否进入市场。他们让 Skill 先在 GitHub sandbox 文件夹里试用，作者通过 Slack 等渠道邀请同事尝试。等 Skill 有了使用 traction，owner 再提交 PR 把它移入 marketplace。
这个机制很工程化：先让使用证明价值，再提高分发层级。
组合与度量
Skill 之间可以互相引用。Anthropic 举了文件上传和 CSV 生成的例子：一个 Skill 生成 CSV，另一个 Skill 上传文件。当前 marketplace 或 Skill 本身还没有原生依赖管理，但你可以在说明里按名称引用其他 Skill；如果用户已经安装，模型会调用它们。
Anthropic 还会度量 Skill 的实际使用情况。他们使用 PreToolUse hook 记录公司内部的 Skill 调用，从而发现哪些 Skill 很受欢迎，哪些 Skill 触发率低于预期。
这一步容易被忽略。没有度量，Skill 库很快会变成一堆没人知道是否有效的文档。有了使用数据，团队才能决定该改 description、补 Gotchas，还是淘汰一个没人用的 Skill。
对团队的启发
Claude Code 团队的经验可以浓缩成几条实践：
- 从一个具体失败开始写 Skill，不要从宏大框架开始。
- 把 Gotchas 当成主要资产，持续追加。
- 用文件夹承载脚本、模板、参考资料和配置。
- description 写触发条件，让模型能选中它。
- 对高风险任务使用 hooks 和确认步骤。
- 用日志或稳定数据目录保存必要历史。
- 通过使用数据决定哪些 Skill 值得推广。
如果你的团队已经在用 Agent 写代码，可以先挑一个最容易反复出错的流程，写一个小 Skill。比如 PR 验证、内部 CLI 使用、生产发布检查、值班排障路径。
先把一个坑填平。下次 Claude 再走到那里，它就不会假装自己知道。