Claude Code 中的 Skills：Anthropic 内部使用经验与最佳实践

发表于 分类于
AI 工具

前几天在 X 上看到一篇关于 Claude Code Skills 的深度分享，作者是 Anthropic 的 Thariq。文章总结了他们团队内部数百个 Skills 的实战经验，信息量很大，读完收获颇多。

原文链接：https://x.com/trq212/status/2033949937936085378

今天整理一下核心观点，顺便加上自己的一些思考。

一个常见误解

很多人以为 Skills “就是个 Markdown 文件”，放几句提示词而已。

实际上，Skills 是一个完整的文件夹，可以包含脚本、数据、模板等资源。Claude Code 会在合适的时候读取这些内容，就像给一个专家配备了全套工具箱。

这个区别很重要——它决定了你是做一个”简单的提示词模板”，还是做一个”真正能解决问题的智能助手”。

Skills 的九种类型

Thariq 把 Anthropic 内部的 Skills 分了九大类。这个分类很有参考价值，可以对照看看自己的技能库缺了哪一类：

1. 库与 API 参考

解释如何正确使用某个库、CLI 或 SDK。重点是记录边缘案例和常见陷阱，而不是重复文档。

例子：

  • 内部计费库的 edge cases
  • 出口网关的配置和调试方法
  • 某个 SDK 的版本差异

2. 产品验证

描述如何测试代码是否正常工作，常搭配外部工具。

例子：

  • 用 Playwright 跑完整注册流程
  • 用 Stripe 测试卡验证结账流程
  • 需要 TTY 的交互式 CLI 测试

这类 Skills 特别值得投入时间打磨，因为能保证 AI 输出的正确性。

3. 数据获取与分析

连接数据系统和监控平台，包含查询规范、仪表板 ID、常见工作流。

例子：

  • 用户留存率查询
  • Grafana/Datadog 数据源配置
  • 转化率对比分析

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

把重复工作流压缩为一条命令。

例子：

  • 聚合 Ticket、GitHub、Slack 生成站会报告
  • 自动格式化周报
  • 标准化 Ticket 创建流程

5. 代码脚手架与模板

为特定功能生成框架代码。

例子：

  • 新建内部应用（预配置认证、日志、部署）
  • 迁移文件模板 + 常见陷阱
  • 新建服务/工作流的标准结构

6. 代码质量与评审

强制代码质量，帮助代码评审。

例子：

  • 生成”新鲜视角”子 Agent 进行批判性评审
  • 强制特定代码风格
  • 测试编写指南

7. CI/CD 与部署

帮助获取、推送、部署代码。

例子：

  • 监控 PR → 重试 flaky CI → 解决冲突 → 自动合并
  • 渐进式部署 + 错误率监控 → 自动回滚
  • Cherry-pick 到生产环境的标准流程

8. 运行手册 (Runbooks)

输入症状，输出结构化诊断报告。

例子：

  • 某服务的调试手册（症状 → 工具 → 查询映射）
  • On-call 告警自动排查
  • 根据 request ID 关联所有相关日志

9. 基础设施运维

执行日常维护与操作（含破坏性操作，需要防护栏）。

例子：

  • 发现孤儿资源 → 通知 → 浸泡期 → 用户确认 → 清理
  • 依赖审批工作流
  • 成本异常调查

制作 Skills 的实用技巧

1. 不要陈述显而易见的内容

Claude 已经知道很多东西。Skills 应该聚焦在”让 Claude 跳出常规思维”的信息上。

例子：前端设计 Skill 通过与用户迭代，避免 Inter 字体和紫色渐变等”AI 味”设计。

2. 建立 Gotchas 专区（最有价值的内容）

记录 Claude 使用这个 Skill 时常见的失败点，持续更新。

真实例子：

  • “subscriptions 表是 append-only，取最高 version 而非最新 created_at”
  • “API gateway 用 @request_id，billing service 用 trace_id，但值相同”
  • “Staging 返回 200 但 Stripe webhook 未处理，需查 payment_events”

3. 利用文件系统做渐进式披露

Skill 是文件夹，可以把详细内容拆分到不同文件：

  • references/api.md - 详细 API 签名
  • assets/ - 模板文件供复制
  • scripts/ - 现成脚本

让 Claude 知道文件夹内容，它会在需要时读取。

4. 避免过度约束

Skill 要可复用，指令不要过于死板。提供必要信息，保留适应性。

5. 提前考虑配置

部分 Skill 需要用户上下文（如 Slack 频道）。建议用 config.json 存储配置，未配置时让 Agent 询问用户。

6. 内存与数据存储

Skill 内可以实现”内存”：追加日志、JSON 或 SQLite。建议存入稳定路径（如 ~/.claude），避免 Skill 升级时丢失数据。

例子：standup-post 保留 standups.log，下次运行时自动对比昨日变化。

7. 存储脚本 + 生成代码

给 Claude 现成脚本/库，让它专注组合而非重写样板。

8. 按需 Hooks

仅在调用 Skill 时激活的临时 Hooks。

例子：

  • /careful：仅在生产环境阻挡危险命令
  • /freeze：锁定仅允许特定目录的编辑

分发与管理

小规模：检入仓库

直接放在 ./.claude/skills，适合小团队。

大规模：制作 Plugin

通过 Claude Code Plugin 市场分发，避免每个 Skill 都增加上下文负担。

管理市场的经验

  • 无中心化审核团队
  • 开发者先上传到 sandbox 文件夹，在内部渠道推广
  • 获得 traction 后提 PR 进入市场

组合 Skills

直接通过名称引用其他 Skills，模型会自动调用（前提是已安装）。

衡量使用情况

使用 PreToolUse Hook 记录 Skill 使用日志，可以发现哪些是热门 Skill，哪些没人用。

我的几点思考

1. Skills 的本质是”可复用的上下文”

以前用 Claude，每次都要在对话里交代一堆背景信息。Skills 把这些背景”固化”下来，变成可复用的资产。

这和编程里的”抽象”是一个道理——把通用的东西抽出来，下次直接用。

2. Gotchas 比 Reference 更有价值

文档能告诉 Claude “API 怎么用”，但只有实战经验能告诉它 “这里容易踩坑”。

这也是人类工程师的价值所在——不是记得住多少文档，而是知道哪些地方容易出问题。

3. 从”用完即走”到”持续积累”

Thariq 提到他们大多数 Skills 最初只是几行文字 + 一个 gotcha，后来因 Claude 不断碰到新边缘案例而持续完善。

这和我们写代码一样——先跑起来，再迭代优化。不要想着一次做到完美。

4. 对国内用户的现实考量

Claude Code 在国内的使用还有一些门槛（网络、账号、价格）。但这些方法论是通用的：

  • 如果你用 Cursor/Windsurf，可以借鉴这个分类思路整理 .cursorrules
  • 如果你用其他 AI 工具，也可以建立自己的”提示词库”

核心是：有意识地积累和复用上下文，而不是每次都从零开始。

结语

Skills 还处于早期阶段，大家都在摸索最佳用法。这篇分享更像是一个”有用技巧合集”，而非权威指南。

最好的学习方式就是动手实验，不断迭代。

如果你已经在用 Claude Code，不妨从整理一个最常用的工作流开始，把它做成 Skill。你会发现，AI 助手越用越顺手。

参考链接：