🧰 像 Anthropic 团队一样写 Claude Code skill：9 类 skill 和 9 条实战经验

🧰 像 Anthropic 团队一样写 Claude Code skill：9 类 skill 和 9 条实战经验

Claude Code 里的 skill（技能）是一个文件夹，里面装着说明、脚本和资料，AI 遇到对应任务时会自己找到并使用。Anthropic 的 Claude Code 团队每天都在用 skill，Thariq Shihipar（Anthropic）在 claude.dev 上的《Lessons from building Claude Code: How we use skills》中分享了他们的做法。本文总结他们常写的 9 类 skill，以及让 skill 真正有用的 9 条经验，阅读约 15 分钟。

如果还不清楚 skill 是什么，先读 Claude Skills 是什么 和 Claude Code 是什么（均为越南语）。

🧰 准备

  • 已安装 Claude Code（安装免费，使用需要 Claude 付费套餐或 API 账号）。
  • 一件你反复做的事：发周报、改完网站后检查、查销售数据……
  • 项目里的 .claude/skills/ 文件夹，每个 skill 是一个子文件夹，里面有 SKILL.md 文件。

原文指出最常见的误解：skill 不只是一个 markdown 文件。它是一整个文件夹，可以放脚本、模板和数据，供 AI 读取和使用。

🪜 一步一步来

第 1 步：选对 skill 的类型

Anthropic 把自己的 skill 分成 9 类。好的 skill 只属于一类，横跨多类的 skill 会让 AI 混乱。

  1. 库和 API 参考：如何正确使用某个库或命令行工具，附常见陷阱。
  2. 产品验证：描述如何测试产品是否正常。原文说，在 Anthropic 内部，这一类对 Claude 输出质量的提升最明显。
  3. 数据获取与分析：连接存放数据的地方，并说明怎么查询。
  4. 业务流程与团队自动化：比如发站会更新、写每周总结。
  5. 代码脚手架与模板：为某类应用搭好初始框架。
  6. 代码质量与审查：维护团队的代码规范。
  7. CI/CD 与部署：拉取、推送和部署代码。
  8. 故障手册（Runbook）：根据症状（告警、错误信息）写出结构化的排查报告。
  9. 基础设施运维：日常维护，在破坏性操作前设好护栏。

不写代码的人通常从第 3、4 或 8 类开始。

第 2 步：不要写 AI 已经知道的事

skill 应该包含能把 Claude 推离默认做法的内容。比如 Anthropic 的前端设计 skill，就是为了让 Claude 摆脱 Inter 字体和紫色渐变这类常见套路。

第 3 步：写一个 "Gotchas"（陷阱）部分

原文称这是任何 skill 里信息量最高的部分：记录 AI 容易出错的地方，并随时间不断补充。原文的例子：订阅表只能追加不能修改，所以要取的是版本号最高的那一行，而不是最新创建的那一行。

## Gotchas
- [AI 容易搞错的地方] → [正确做法]
- [两个系统里名字不同的字段] → [哪个字段才是对的]

第 4 步：用文件夹拆分，需要时再读

不要把所有内容塞进一个文件。模板放 assets/，参考文档放 references/，脚本放 scripts/，在 SKILL.md 里告诉 Claude 需要时去哪个文件找。这叫渐进式披露（progressive disclosure）：AI 只读相关部分，节省工作记忆。

第 5 步：讲目标，不要逐步硬性规定

与其列出六条具体的 git 命令，原文建议写目标，比如："把这个提交挑到一个干净的分支上。解决冲突时保留原本意图。"提供信息和约束，但给 Claude 留出灵活空间。

第 6 步：考虑好初始配置

把配置信息（发到哪个 Slack 频道、用哪张数据表）存在 skill 的 config.json 里。如果还没配置，让 Claude 用清晰的选项询问用户。

第 7 步：描述写给 AI 看，不是写给人看

描述（description）不是摘要。它是 Claude 用来决定是否使用这个 skill 的依据，所以要写进用户常说的话。原文例子：

description: 盯着一个 PR 直到合并。
当用户说"帮我看着"、"盯一下 CI"、"确保这个能合进去"时使用。

第 8 步：帮 Claude 记住，并复用脚本

  • 一个只追加的日志文件（比如放在 ${CLAUDE_PLUGIN_DATA} 变量指向的文件夹里），能让 Claude 记得上次做了什么。
  • 在 skill 里提供辅助函数，并在函数说明里写明陷阱，让 Claude 组合使用，而不是从头重写样板代码。

第 9 步：只在调用时启用护栏

skill 可以只在被使用时开启 hook（自动检查）。Anthropic 的例子：/careful 在操作生产环境时拦截危险命令，/freeze 只允许修改指定文件夹。

✅ 示例结果

一个整洁的"周报" skill 可能长这样：

.claude/skills/weekly-report/
├── SKILL.md          # 目标、主要步骤、Gotchas
├── config.json       # 报告发到哪里、用哪张数据表
├── references/
│   └── metrics.md    # 每个指标的含义
└── assets/
    └── template.md   # 报告模板

SKILL.md 里的描述："根据销售数据写周报。用户说'周报'、'本周总结'、'weekly recap'时使用。"Gotchas 部分写："收入按付款日期计算，不按下单日期。"

💡 让结果更好的技巧

  • 从小处开始。 原文的结论：他们最好的 skill 大多一开始只有几行和一个陷阱，之后每当 Claude 遇到新情况，大家不断补充，才越来越好。
  • 用对分享方式。 小团队把 skill 直接放在代码仓库里（.claude/skills）。大团队做一个插件市场，让每个人按需安装。
  • 统计哪些 skill 被用到。 Anthropic 用 hook 记录 skill 的使用情况，看哪些受欢迎，哪些被调用得比预期少。
  • 读一读 CLAUDE.md，帮 Claude 记住一切的说明书，判断哪些内容该放进 CLAUDE.md，哪些该拆成 skill。

⚠️ 需要知道的限制

  • skill 不能代替你自己的检查。 尤其是部署代码或删除数据的 skill：始终保留确认步骤。
  • 不要在 skill 文件里放密码或 API 密钥，如果这个文件夹会被分享或推到 GitHub。
  • 别人写的 skill 在你电脑上拥有和 Claude Code 一样的权限。 只安装你信任来源的 skill。
  • skill 的做法还在变化，原文本身也说最佳实践仍在演进。

❓ 常见问题

skill 和 CLAUDE.md 有什么区别？ CLAUDE.md 在每次会话开始时都会被读取，所以要保持简短。skill 只在遇到对应任务时才加载，因此可以放长说明、模板和脚本，而不会挤占 AI 的记忆。

不会写代码的人能写 skill 吗？ 能。最基础的 skill 就是一个文本文件，写清目标、主要步骤和常见陷阱。你也可以让 Claude Code 先起草，再自己修改。

第一个 skill 写哪一类好？ 按原文的说法，产品验证类 skill 对质量提升最大。对做内容或运营的人来说，为每周重复的工作写一个 skill 最容易上手。

为什么 Claude 不会自动用我的 skill？ 通常是因为描述写得像给人看的摘要。把用户需要这件事时常说的话加进去。

这些内容出自哪里？ 出自 Thariq Shihipar 在 claude.dev 上的《Lessons from building Claude Code: How we use skills》，claude.dev 是 Anthropic 开发者分享经验的网站。

更多文章