Claude Code Skill 实战：从「能用」到「好用」

最近在读 Anthropic 工程师 Thariq 分享的一篇关于 Skill 的实战总结，有一句话值得单独拿出来看：

Skills have become one of the most used extension points in Claude Code... A common misconception we hear about skills is that they are "just markdown files", but the most interesting part of skills is that they're not just text files. They're folders that can include scripts, assets, data, etc. that the agent can discover, explore and manipulate.

Skill 不是提示词模板，而是一个可以带脚本、数据和配置的文件夹。

这和大部分人的用法不太一样。多数开发者接触 Skill 的路径是：新建一个 Markdown 文件，写几段提示词，用 /my-skill 调用一下，觉得"也就那样"。但 Anthropic 内部有数百个 Skill 在日常跑着，形态比单个 Markdown 文件丰富得多。

这篇文章面向已经用过 Claude Code、写过一两个 Skill 的工程师，整理一下怎么把 Skill 写得更好用。

太长不看版

1. Skill 是文件夹，不是文件。脚本、模板、配置文件都可以放进去，Claude 会自动发现和使用
2. Anthropic 内部的 Skill 聚成九大类：知识、验证、数据观测、工作流自动化、脚手架、代码质量、DevOps、问题排查、运维维护
3. Skill 里最有用的部分是 Gotchas，Claude 踩过的坑比正面指令更有效
4. 用渐进式披露管理上下文：主文件给方向，子文件给细节
5. 写 Skill 要灵活，给 Claude 适应空间，说清意图和顺序就够了
6. 用 config.json 存储用户配置，让 Skill 适配不同环境
7. 给 Skill 配脚本和库，让 Claude 专注编排而不是重复写样板代码
8. Skill 可以注册作用域内的 Hooks，调用时才生效
9. 团队共享有两条路：提交到仓库的 .claude/skills/ 或通过插件市场分发
10. Skill 需要持续维护，模型升级、工具链变化都需要适配

Skill 不只是一个 Markdown 文件

多数人写 Skill 的方式是：新建一个 .md 文件，写几段提示词，用 /my-skill 调用。这能跑，但没用到 Skill 的完整能力。

Skill 的载体是一个文件夹。除了主指令文件，还可以放参考文档、代码模板、验证脚本、配置文件。Claude 会自动发现这些文件，在需要时读取。

一个典型的 Skill 目录结构长这样：

.claude/skills/my-skill/
├── SKILL.md              # 主指令文件
├── references/
│   └── api.md            # 详细 API 参考（按需加载）
├── assets/
│   └── template.tsx      # 模板文件
├── scripts/
│   └── validate.sh       # 验证脚本
└── config.json           # 用户配置（可选）

Claude 启动时扫描所有 Skill 的 description 建索引。调用某个 Skill 时，加载主文件指令，Claude 按需探索文件夹中的其他文件。

Thariq 把这叫"渐进式披露"：主文件给方向，子文件给细节，Claude 自己判断什么时候需要看什么。

九大分类：你的 Skill 库缺了哪几块？

Anthropic 内部梳理了所有在用的 Skill，发现它们聚成九个类别。好的 Skill 干净地落在某一类里，让人困惑的 Skill 往往横跨好几类。

这不是标准答案，但可以当自检清单用，看看你的团队在哪些方向上还是空白。

1. 知识类（Knowledge Skills）

解释如何正确使用某个库、CLI 或 SDK。可以是内部库，也可以是 Claude 经常用错的公共库。

这类 Skill 通常包含一个参考代码片段文件夹和一份 Claude 容易踩坑的清单。

.claude/skills/billing-lib/
├── SKILL.md           # 使用说明 + 常见误区
├── references/
│   ├── api.md         # 完整 API 签名
│   └── examples.md    # 正确用法示例
└── gotchas.md         # 踩坑记录

典型场景：

• billing-lib ------ 内部计费库的边界情况和易错点
• internal-platform-cli ------ 内部 CLI 的每个子命令及使用场景
• frontend-design ------ 让 Claude 更好地使用你的设计系统

2. 验证类（Verification Skills）

描述如何测试或验证代码是否正常工作。通常搭配 Playwright、tmux 等外部工具。

Thariq 的原话是：验证类 Skill 值得一个工程师花一整周来打磨。可以让 Claude 录制测试过程的视频，或者在每一步做程序化断言。

典型场景：

• signup-flow-driver ------ 在无头浏览器中跑完注册、邮箱验证、引导流程，每步断言状态
• checkout-verifier ------ 用 Stripe 测试卡驱动结账 UI，验证发票状态
• tmux-cli-driver ------ 需要 TTY 的交互式 CLI 测试

3. 数据与观测类（Data & Observability Skills）

连接你的数据和监控栈，包含数据获取脚本、Dashboard ID、常用查询工作流等。

典型场景：

• funnel-query ------ "注册到激活到付费要 join 哪些事件"，加上 canonical user_id 所在的表
• grafana ------ 数据源 UID、集群名称、问题到 Dashboard 的映射表

4. 工作流自动化类（Workflow Automation Skills）

把重复性工作流打包成一条命令。指令通常不复杂，但会依赖其他 Skill 或 MCP。

一个实用技巧：让 Skill 把每次执行结果写入日志文件，Claude 后续执行时可以参考历史记录，保持一致性。

典型场景：

• standup-post ------ 聚合 Ticket、GitHub 活动和 Slack 消息，生成格式化的站会汇报
• weekly-recap ------ 合并 PR + 关闭 Ticket + 部署记录，生成周报

5. 脚手架类（Scaffolding Skills）

为代码库中的特定功能生成框架样板。当你的脚手架有自然语言需求（纯代码模板覆盖不了的部分）时特别有用。

典型场景：

• new-migration ------ 迁移文件模板 + 常见陷阱
• create-app ------ 预装了认证、日志和部署配置的新应用模板

6. 代码质量类（Code Quality Skills）

在组织内强制执行代码质量标准。可以包含确定性脚本以获得最大稳健性，也可以作为 Hooks 或 GitHub Action 的一部分自动运行。

典型场景：

• adversarial-review ------ 生成一个"新鲜眼睛"子 Agent 来挑刺，修复后迭代，直到只剩 nitpick
• code-style ------ 强制执行 Claude 默认做不好的代码风格
• testing-practices ------ 如何写测试、测什么

7. DevOps 类

帮你拉取、推送和部署代码。

典型场景：

• babysit-pr ------ 监控 PR，重试 flaky CI，解决合并冲突，启用自动合并
• deploy-service ------ 构建、冒烟测试、灰度发布、错误率对比、自动回滚
• cherry-pick-prod ------ 隔离 worktree、cherry-pick、冲突解决、按模板创建 PR

8. 问题排查类（Triage & Debugging Skills）

接收一个症状（Slack 线程、告警、错误签名），走完多工具调查流程，输出结构化报告。

典型场景：

• service-debugging ------ 症状到工具到查询模式的映射
• oncall-runner ------ 拉取告警、检查常见嫌疑、格式化发现
• log-correlator ------ 给定 request ID，从所有相关系统拉取匹配日志

9. 运维维护类（Maintenance & Operations Skills）

执行例行维护和运维操作，其中一些涉及破坏性操作，需要护栏。

典型场景：

• orphan-cleaner ------ 找到孤立 Pod/Volume，发到 Slack，等待确认后级联清理
• dependency-management ------ 组织内的依赖审批工作流
• cost-investigation ------ "为什么存储/出口带宽账单飙了"，附带具体的 bucket 和查询模式

八个技巧：怎么把 Skill 写好

分类只是方向，真正决定 Skill 好不好用的是写法。以下是 Anthropic 内部总结的经验。

技巧一：聚焦非默认知识

Claude 对你的代码库已经有不少了解，对编程本身更是熟悉。知识类 Skill 应该重点写那些 Claude 不知道的、你们团队特有的信息。

不要告诉 Claude "怎么写 React 组件"，告诉它"我们的 React 组件有哪些不走寻常路的约定"。

技巧二：持续积累 Gotchas

Skill 里信号密度最高的部分是 Gotchas。这些应该从 Claude 实际踩坑中积累。

每次 Claude 在某个 Skill 上犯错，就把这个错误加到 Gotchas 里。时间一长，Gotchas 会变成 Skill 里最有用的部分。

## Gotchas

- 不要用 `client.query()` 的默认超时，我们的数据库集群在高峰期需要至少 30s
- `user_id` 字段在 events 表里叫 `uid`，不是 `user_id`
- 创建 migration 后必须先跑 `make generate`，否则 ORM 类型不会更新

技巧三：用渐进式披露管理上下文

Skill 是一个文件夹，不只是一个 Markdown 文件。把文件系统当作上下文管理的手段。

做法很简单：在主文件里列出子文件的路径和用途，Claude 会在合适的时机自己去读。

## 参考资料

- 详细的 API 签名和用法示例见 `references/api.md`
- 模板文件在 `assets/` 目录下，创建新组件时直接复制使用
- 常见问题排查流程见 `references/troubleshooting.md`

这比把所有内容塞进一个大 Markdown 文件好，既省 token，又让 Claude 按需获取信息。

技巧四：灵活而非死板

Skill 会被反复使用，过于具体的指令反而成为限制。给 Claude 足够的信息，同时留出适应空间。

关键在于：不需要事无巨细地说明使用什么命令、如何做具体某个操作，而是表明意图和要做的具体顺序内容。Claude 知道怎么执行，你要告诉它的是"做什么"和"按什么顺序做"，而不是"怎么敲键盘"。

# 过于死板
创建组件时必须使用以下精确模板，不得修改任何部分...
执行 mkdir -p src/components/MyComponent
执行 cp template.tsx src/components/MyComponent/index.tsx
执行 sed -i 's/Template/MyComponent/g' ...

# 灵活适应
创建组件时参考 `assets/template.tsx` 的结构。
根据具体需求调整，但保持以下约定：
- 使用 named export
- Props 类型定义放在组件上方
- 错误边界用 ErrorBoundary 组件包裹

技巧五：写好 Description

Claude Code 启动时会用 description 字段建索引。description 不是摘要，是触发条件，告诉 Claude 什么场景下该用这个 Skill。

---
# 当摘要写------太模糊，Claude 不知道什么时候该触发
description: "一个用于处理数据库迁移的工具"

# 当触发条件写------明确场景，Claude 能准确匹配
description: "当需要创建、修改或回滚数据库迁移文件时使用。
  适用于 schema 变更、数据迁移和索引操作。"
---

技巧六：用 Config 文件做初始化

有些 Skill 需要用户提供上下文才能工作，比如数据库连接串、服务名称、Slack 频道。做法是在 Skill 目录下放一个 config.json，配置不存在时 Claude 会主动询问用户并写入。

// .claude/skills/deploy-service/config.json
{
  "service_name": "user-api",
  "staging_url": "https://staging.example.com",
  "slack_channel": "#deploys",
  "rollback_threshold_error_rate": 0.05
}

这样 Skill 第一次运行时会引导用户完成配置，后续执行就不需要重复输入了。

技巧七：给 Skill 配脚本和库

给 Skill 配上脚本和库，Claude 就可以把精力花在编排和决策上，不用每次从头写样板代码。

比如一个验证类 Skill，与其在 Markdown 里写一大段"如何用 Playwright 测试登录流程"，不如直接提供一个封装好的测试脚本：

.claude/skills/signup-verifier/
├── SKILL.md
├── scripts/
│   ├── run-flow.ts        # 封装好的 Playwright 测试流程
│   ├── assert-state.ts    # 状态断言工具
│   └── capture-video.ts   # 录制测试视频
└── lib/
    └── test-helpers.ts    # 公共测试辅助函数

Claude 拿到这些脚本后，只需要决定什么时候调用哪个、传什么参数，不用每次从零写测试代码。执行的稳定性和一致性都会好很多。

技巧八：给 Skill 加记忆

有些 Skill 可以在目录内存储数据来实现记忆，简单的用追加写入的文本日志，复杂的可以用 SQLite。

注意 Skill 目录内的数据在升级时可能被删除，稳定的存储路径应该用 ${CLAUDE_PLUGIN_DATA}。

## 执行记录

每次执行后，将结果摘要追加到 `${CLAUDE_PLUGIN_DATA}/execution-log.jsonl`：
- 时间戳
- 执行参数
- 成功/失败
- 关键输出

下次执行时先读取最近 5 条记录，保持一致性。

Skill 作用域 Hooks：调用时才生效的守卫

Skill 可以注册只在被调用时激活、持续到会话结束的 Hooks。这意味着你可以做"模式切换"类的 Skill：

• /careful，通过 PreToolUse 匹配器拦截 rm -rf、DROP TABLE、force-push、kubectl delete
• /freeze，阻止对特定目录之外的任何 Edit/Write 操作

这些 Hooks 只在你主动调用对应 Skill 时才启动，比全局配置里加一堆防护规则干净得多。需要的时候开，不需要的时候不碍事。

团队共享

Skill 写好了，怎么让团队用上？两条路：

提交到仓库：把 Skill 放在 .claude/skills/ 目录下，随代码一起版本管理。适合小团队。

插件市场：做成 Claude Code Plugin，通过内部插件市场分发。适合需要跨团队分发的组织。

不管哪条路，Skill 应该像代码一样被维护。有人用、有人改、有人加 Gotchas，它才会越来越好。Anthropic 内部大部分 Skill 都是从几行文字和一条 Gotcha 开始的，因为不断有人在 Claude 踩坑后往里面加东西，才变成了现在的样子。

---

写 Skill 和写代码一样，不是一次写完就结束了。模型在升级，工具链在变，团队的工程实践也在调整。今天好用的 Skill，过几个月可能就需要改。 从你最痛的那个重复性工作开始，写一个最小的 Skill，跑起来，每次 Claude 犯错或执行遇到问题就加一条 Gotcha更新优化。