大家好，我是 Immerse

专注分享 AI 玩法、独立开发与AI 出海的 AGI 实践者，更多干货欢迎关注公众号 #沉浸式AI 或访问 yaolifeng.com

AI News 站更新啦：news.yaolifeng.com

---

Anthropic 工程师 Thariq 最近在 X 上发了一篇长文，说他们公司内部现在有上百个 Skills 在跑，整理了一批踩坑经验。

大多数人第一次接触 Claude Code Skills，以为它就是个 Markdown 文件——写点提示词，丢进去，完事。

实际上 Skills 是文件夹，不是文件。里面可以放脚本、资产、数据、配置，整个目录结构都是上下文工程的一部分。

这篇文章整理他们的方法论：Skills 的分类体系、写好一个 Skill 的关键技巧，以及团队内部怎么分发和管理。

9 种类型

他们把内部所有 Skills 整理了一遍，大概在这几个方向上

1. 库和 API 参考

用来解释如何正确用某个库、CLI 或 SDK。不管是内部自己的库，还是 Claude 经常用错的外部库，都可以做成这类 Skill。

这类 Skills 通常带一个 references/ 文件夹，里面包含一个参考代码片段和踩坑清单。

比如：

• billing-lib — 公司内部库，重点是边界情况和容易踩的坑
• internal-platform-cli — 内部 CLI 工具的每个子命令，以及使用示例
• frontend-design — 让 Claude 更好地理解你们的设计系统

2. 产品验证

描述怎么测试或验证代码能不能正确运行。一般配合 Playwright、tmux 使用。

Thariq 说得很直接：让一个工程师花一整周专门打磨验证 Skill，这个时间花得值

比如：

• signup-flow-driver — 跑完整的注册流程（注册 → 邮件验证 → 引导），用 headless 浏览器，每步都有状态断言
• checkout-verifier — 用 Stripe 测试卡驱动结账 UI，验证发票状态落地是否正确
• tmux-cli-driver — 交互式 CLI 测试，用于需要 TTY 的场景

3. 数据获取和分析

连接你的数据和监控系统。这类 Skill 会带上权限凭证的数据获取库、dashboard ID，以及常见的一些操作指南。

比如：

• funnel-query — "注册 → 激活 → 付费"这条漏斗用哪些事件表 JOIN，canonical user_id 在哪张表
• cohort-compare — 对比两个用户群的留存或转化，标记统计显著的差异，链接到细分定义
• grafana — datasource UID、集群名称、问题到仪表盘的映射表

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

把重复的工作流自动化成一个命令。指令本身通常比较简单，但可能依赖其他 Skill 或 MCP。

可以把历史执行结果存进日志文件是个好习惯，可以帮 Claude 做前后对比，而不是每次从头开始。

比如：

• standup-post — 汇总你的 ticket 系统、GitHub 动态和昨天的 Slack，生成只有增量变化的站会帖子
• create-ticket — 强制执行字段 schema（枚举值、必填字段），创建后自动触发后续流程（通知审核人、在 Slack 贴链接）
• weekly-recap — 合并的 PR + 关闭的 ticket + 部署记录，格式化成周报

5. 代码脚手架和模板

为代码库里的某个功能生成框架代码。这类 Skill 特别适合那些有自然语言要求、纯代码覆盖不了的脚手架场景。

比如：

• new-workflow — 按你们的注解规范，生成新 service/workflow/handler 的脚手架
• new-migration — 数据库迁移文件模板，附带常见坑
• create-app — 新建内部应用，预置好你们的 auth、日志和部署配置

6. 代码质量和审查

在团队内部执行代码质量标准，辅助代码审查。可以包含确定性脚本，也可以在 hooks 或 GitHub Actions 里自动触发。

• adversarial-review — 起一个新的 subagent 用全新视角批判代码，实现修复，迭代直到问题只剩鸡毛蒜皮
• code-style — 强制执行代码风格，尤其是 Claude 默认不做的那些规范
• testing-practices — 指导怎么写测试、测什么

7. CI/CD 和部署

帮助拉取、推送、部署代码，可能会引用其他 Skill 来收集数据。

比如：

• babysit-pr — 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 开启自动合并
• deploy-service — 构建 → 冒烟测试 → 灰度流量 + 错误率对比 → 自动回滚
• cherry-pick-prod — 隔离 worktree → cherry-pick → 解决冲突 → 附模板的 PR

8. Runbooks

接收一个问题症状（Slack 线程、告警、错误特征），它会执行多工具调查，输出结构化报告。

比如：

• service-debugging — 把症状映射到工具和查询模式，针对流量最高的服务
• oncall-runner — 拉取告警 → 检查常见嫌疑点 → 格式化调查结论
• log-correlator — 给一个 request ID，从所有可能经过的系统里拉对应日志

9. 基础设施运维

执行日常维护和操作流程。破坏性操作放进 Skill 可以一层护栏，避免手滑导致不可逆的风险

比如：

• orphans-cleanup — 找孤立的 pod/volume → 发 Slack → 等待期 → 用户确认 → 级联清理
• dependency-management — 你们组织的依赖审批流程
• cost-investigation — "为什么存储/出流量账单突然涨了"，定位到具体 bucket 和查询模式

写好一个 Skill 的关键技巧

不要放很常识的东西

Claude 已经懂很多编码知识，有自己的默认判断。如果你写的 Skill 主要是常识，它没什么价值。要把精力放在那些会把 Claude 推出默认思维的信息上。

Anthropic 内部的 frontend-design Skill 是个好例子——一个工程师跟用户迭代，专门调教 Claude 的设计品味，让它避开 Inter 字体和紫色渐变这类 AI 审美。这类东西 Claude 默认是不知道的。

Gotchas 部分信噪比最高

一个 Skill 里信噪比最高的部分就是 Gotchas。这里记录 Claude 实际使用你的 Skill 时踩过的坑——不是你预测它会踩的，是真的踩了的。边用边更新，遇到新的 edge case 就补进去。

Skill 是文件夹，不是 md 文件

把整个文件系统当成一种上下文工程和渐进式披露的手段。在 SKILL.md 里告诉 Claude 有哪些文件，它会在合适的时候去读。

最简单的做法是把详细内容拆到其他 md 文件里。比如函数签名和用法示例单独放到 references/api.md，Claude 需要的时候再去读，而不是一开始就全部加载进上下文。

你还可以这样组织：

• assets/ 放模板文件，Claude 要生成对应格式的输出时直接复制用
• scripts/ 放可以直接调用的工具脚本
• references/ 放参考代码片段和文档

给 Claude 信息，不要给 Claude 剧本

因为 Skill 是高度复用的，过于具体的指令反而会出问题。给 Claude 它需要的信息，但给它适应当前情况的空间。不要把每一步都写死，把判断权留给 Claude。

Setup 环节要想清楚

有些 Skill 需要用户提供上下文才能工作

最常见模式：配置信息存在 Skill 目录下的 config.json 里，如果配置不存在，Agent 去问用户。要给出结构化的多选题，可以在 Skill 里指示使用 AskUserQuestion 工具。

description 字段是给模型看的触发条件

Claude Code 启动时会给每个 Skill 建一个带 description 的列表，扫这个列表来判断「有没有对应这个请求的 Skill」。所以 description 要写清楚触发时机，而不是 Skill 功能的摘要。

Skills 可以有记忆

Skill 里可以包含一种记忆，通过在 Skill 目录里存数据实现。从简单的 append-only 文本日志、JSON 文件，到复杂的 SQLite 数据库都可以。

比如 standup-post Skill 维护一个 standups.log，记录每次写的内容，下次运行时 Claude 读自己的历史，知道哪些是新变化。

注意：存在 Skill 目录里的数据升级时可能被删掉。持久数据应该存到 ${CLAUDE_PLUGIN_DATA}，这是每个插件独立的稳定存储路径。

在 Skills 里放脚本

给 Claude 代码比给指令有效得多。有了脚本和库，Claude 就能把时间花在组合和决策上，而不是每次从头重建样板代码。

比如数据科学类 Skill 里放一组从事件源取数的 helper 函数，Claude 就可以按需动态生成脚本来做进一步分析，而不是每次自己写逻辑。

按需 Hooks

Skill 可以包含只在 Skill 被调用时激活的 hooks，持续到这个 session 结束。这适合那些场景特定、不想一直开着的强约束 hook。

两个典型例子：

• /careful — 通过 PreToolUse matcher 拦截 rm -rf、DROP TABLE、force-push、kubectl delete。只在你知道自己要动 prod 的时候才需要，常开会让人崩溃
• /freeze — 拦截所有不在指定目录里的 Edit/Write。调试时很有用："我想加日志，但我总是顺手把别的东西改了"

怎么在团队里分发 Skills

分发方式取决于团队规模：

小团队：把 Skills 提交进代码仓库（./.claude/skills 目录）。团队人不多、仓库也不多的情况下，这样最简单直接。

大团队：搭内部插件市场，按需安装。这是因为每个提交进仓库的 Skill 都会给模型的上下文增加一点点体积，规模大了之后就不可忽视了。内部市场让每个人自己决定装哪些。

Skills 互相引用

如果你有一个 Skill 要依赖另一个 Skill，直接在指令里引用另一个 Skill 的名字就行，Claude 会在它已安装的情况下调用它。这个依赖管理目前还没有原生的 Skill 系统支持，但这种方式能跑通。

Skill 使用情况

Anthropic 用 PreToolUse hook 记录公司内部的 Skill 使用情况。这样能看到哪些 Skill 频繁被用，哪些触发率低于预期——后者意味着 description 没写好，或者这个 Skill 根本没解决真实需求。

发现 Skill 很少被触发，先检查 description 是不是清楚地描述了触发场景。

---

大部分 Skill 在 Anthropic 内部也是从几行指令、一个 Gotcha 开始的，遇到新 edge case 就补进去，慢慢变好的。挑一件你每天重复干的事，写一个最简版，先跑通。