--- title: "Skill 设计手册：Anthropic 内部数百个 Skill 的经验总结" author: deletexiumu pubDatetime: 2026-03-18T12:00:00+08:00 featured: false draft: false tags: - Claude Code - AI Agent - 教程 description: "基于 Anthropic 工程师 Thariq 的官方分享，系统梳理 Claude Code Skill 的 9 大分类与 9 大设计技巧，附可复制的 SKILL.md 模板和设计评估清单。" --- 前一篇（《从需求到自动化：Claude Code Skill 工具链完整实战》）讲的是**怎么把一个任务做成 Skill 工具链**——从 Brainstorming 到 dev browser 到 Skill Creator，走的是"从零到一"的路线。那篇解决的问题是：我有一个需求，怎么一步步把它变成一个可复用的 Skill。 这一篇换个角度。不讲"怎么做"，讲**"怎么做好"**。 2026 年 3 月 17 日，Anthropic Claude Code 团队工程师 Thariq（@trq212）发了一篇长文，系统梳理了 Anthropic 内部数百个 Skill 的设计经验。这篇文章迅速拿到 200 万+ 阅读、7600+ 点赞，社区直接把它称为"the GOAT write-up"。韩国开发者 @supernovajunn 的总结很直接："做 Skill 做得好的人赢了。" Thariq 自己说这篇花了一周半写完——"Claude 做了调研和分类，但大部分文案我扔掉重写了"。这说明即使是 Anthropic 内部，Skill 的设计也不是靠模型生成就能搞定的事。 我读完后最大的感受是：**大多数人（包括我自己）之前写 Skill 的方式都太粗糙了**。我们把 Skill 当成一张提示词纸条，但 Anthropic 内部把它当作一个可组合的文件夹资产来设计。这个认知差距不是小事。 本文基于 Thariq 的原文，结合我自己的实践经验，重新组织成一份**可操作的 Skill 设计手册**。不是翻译，是提炼 + 补充 + 给模板。 --- ## 一、Skill 全景地图：9 大类型 先建立全局认知。Thariq 把 Anthropic 内部的 Skill 归纳为 9 个大类： | 类型 | 一句话定义 | 典型案例 | |------|-----------|---------| | Library & API Reference | 内部库/SDK 的使用指南与踩坑手册 | billing-lib、frontend-design | | Product Verification | 让 Claude 自己测试自己写的代码 | signup-flow-driver、checkout-verifier | | Data Fetching & Analysis | 连接数据源和监控栈做分析 | funnel-query、grafana | | Business Process & Team Automation | 重复工作流一键化 | standup-post、weekly-recap | | Code Scaffolding & Templates | 标准化项目/功能脚手架生成 | new-workflow、new-migration | | Code Quality & Review | 自动化代码审查与质量守护 | adversarial-review、code-style | | CI/CD & Deployment | 从提交到上线的流水线操作 | babysit-pr、deploy-service | | Runbooks | 故障排查自动化 | service-debugging、oncall-runner | | Infrastructure Operations | 带护栏的基础设施运维操作 | resource-orphans、cost-investigation | ![9大Skill分类全景](/blog/claude-code-skill-design-guide/01-skill-categories.png) 9 类全列出来了，但不是每类都值得花同样的时间。下面挑 3 类深入聊——它们要么最常见，要么最有启发性，要么最容易踩坑。 --- ## 二、最值得投入的 3 类 Skill ### 2.1 Product Verification：让 Claude 验证自己的输出 Thariq 原话：**"验证 Skill 值得一个工程师花一周时间来做好。"** 这句话的分量很重——Anthropic 内部认为，验证比写代码本身更值得投入。 道理不复杂。Claude 写代码的速度很快，但"写完就提交"和"写完验证再提交"之间的质量差距是巨大的。Product Verification Skill 做的事情是：定义一套程序化的验证流程，让 Claude 在完成编码后自动跑一遍。 关键技巧： - **录制输出视频**：搭配 Playwright 等工具，Claude 操作界面时录屏，出错时你能回放定位 - **每步程序化断言**：不是让 Claude 自己判断"看起来对不对"，而是用具体的断言（元素存在、响应码、数据一致性）来验证 - **搭配 tmux**：CLI 场景下用 tmux 做会话管理，Claude 可以在一个窗口跑服务、另一个窗口跑测试 我自己的体会是，Product Verification 是投入产出比最高的 Skill 类型。写一次，后面每次 Claude 提交代码前都会自动跑验证，等于给 AI 编程加了一层自动化 QA。 ### 2.2 Library & API Reference：补偏差，不补常识 这是最常见的 Skill 类型，也是最容易写成废话的类型。 核心原则只有一条：**Claude 已经知道的东西不需要重复**。Claude 的训练数据里有大量公开库的文档，你把 React 的基本用法再写一遍，纯属浪费 context。 Library Skill 真正有价值的部分是： - Claude 不知道的内部库用法 - Claude 知道但容易犯错的边界情况 - 你踩过的坑（gotchas） ![billing-lib示例](/blog/claude-code-skill-design-guide/01-billing-lib-example.jpg) 比如上面的 billing-lib 示例，它不会教你怎么调用这个库——Claude 读源码就能搞定。它记录的是"这个接口在金额为 0 时的行为和你想的不一样"这类信息。 另一个好例子是 frontend-design Skill——它不教 Claude 写 CSS，而是调教 Claude 的设计品味。这个 Skill 是 Anthropic 工程师反复迭代出来的，目标是让 Claude 的 UI 输出从"能用"变成"好看"。 ### 2.3 Infrastructure Operations：危险操作需要护栏 这类 Skill 涉及破坏性操作——清理孤立资源、删除过期数据、管理依赖版本。没有护栏的话，Claude 可能真的会执行 `rm -rf` 或者 `DROP TABLE`。 Thariq 描述的模式叫 **Safety-gated cleanup**，流程是： 1. 扫描 → 发现需要处理的资源 2. 通知 → 列出将要执行的操作 3. 等待期 → 给人类确认的时间窗口 4. 确认 → 用户明确同意后才执行 5. 清理 → 执行实际操作 这个模式搭配 On-Demand Hooks（后面会详细讲）效果更好。比如一个叫 `careful` 的 hook，只在你明确说"我要操作生产环境"时才激活，激活后它会拦截所有 `rm -rf`、`DROP TABLE`、`force-push` 操作。 --- ## 三、Skill 设计三层法则：9 大编写技巧 Thariq 的 9 个编写技巧如果平铺来看会显得零散。我把它们按设计层级重组成三层：**触发层、执行层、持久层**。 ![9大技巧总览](/blog/claude-code-skill-design-guide/02-tips-overview.png) ### 3.1 触发层：让 Claude 找到你的 Skill #### Description = 触发条件，不是摘要 这是最多人搞错的一点。SKILL.md 里的 `description` 字段**不是给人看的**——它是给模型看的触发条件。 Claude Code 启动时，会把所有已安装 Skill 的 description 构建成一个列表。用户发消息后，Claude 根据这个列表决定"要不要调用某个 Skill"。所以 description 的写法直接决定了你的 Skill 能不能被正确触发。 ![触发描述对比](/blog/claude-code-skill-design-guide/03-description-comparison.png) 差的写法： ``` A comprehensive tool for monitoring pull request status across the development lifecycle. ``` 这句话信息密度很低，Claude 看到用户说"帮我盯着这个 PR"时，不一定能匹配上。 好的写法： ``` Monitors a PR until it merges. Trigger on 'babysit', 'watch CI', 'make sure this lands'. ``` 直接告诉模型：用户说哪些词的时候应该调用我。这不是在写产品说明书，这是在写搜索索引。 社区的痛点也印证了这一点。@svpino 抱怨说"Skills 现在是猫鼠游戏，今天能用，明天就失败了"——很多时候触发不稳定的根源就是 description 写得太模糊。 #### Think Through Setup：设计初始化流程 有些 Skill 第一次运行时需要用户提供配置信息——API key、目标仓库、通知频道等。 好的做法是设计一个配置引导流程： ![standup-post配置](/blog/claude-code-skill-design-guide/03-standup-post-config.jpg) config.json 示例： ```json { "slack_channel": "#team-standup", "template": "bullet-points", "include_yesterday": true } ``` 在 SKILL.md 里这样写： ```markdown ## Setup Read `config.json` for runtime settings. If config.json doesn't exist, ask the user to configure: - Slack channel for posting - Preferred format (bullet-points / paragraph) - Whether to include yesterday's summary Save responses to config.json for future runs. ``` 这样用户只需要配置一次，后续运行直接读取。你也可以让 Claude 用 `AskUserQuestion` 工具展示结构化选择题，降低用户的输入负担。 ### 3.2 执行层：让 Skill 真正有用 #### Skip the Obvious：不说 Claude 已经知道的 Claude 对主流编程语言、框架、库有很强的基础知识。你在 Skill 里重复 "使用 `try-catch` 处理异常"、"记得写单元测试" 这类话，只是浪费 context window。 有效的内容是**推动 Claude 偏离默认行为的信息**。Claude 默认会按最常见的方式写代码，但你的项目可能有不同的约定——这些才是需要写进 Skill 的。 #### Build Gotchas：信噪比最高的内容 Gotchas（踩坑清单）是 Skill 里投入产出比最高的部分。Thariq 的建议是：**从 Claude 使用 Skill 时的实际失败点积累，而不是凭空想象。** 一个好的 Gotchas 段落会随时间演化： ![踩坑清单演化](/blog/claude-code-skill-design-guide/04-gotchas-evolution.png) **Day 1**（刚创建 Skill 时）： ```markdown ## Gotchas - `createInvoice()` 的金额参数是分，不是元。传 1000 表示 10.00 元 ``` **Month 1**（用了一段时间后）： ```markdown ## Gotchas - `createInvoice()` 的金额参数是分，不是元。传 1000 表示 10.00 元 - 退款接口有 24 小时冷却期，重复调用会返回 429 - 测试环境的 webhook 回调地址和生产环境不同，需要在 config 里区分 ``` **Month 3**（稳定期）： ```markdown ## Gotchas - `createInvoice()` 的金额参数是分，不是元。传 1000 表示 10.00 元 - 退款接口有 24 小时冷却期，重复调用会返回 429 - 测试环境的 webhook 回调地址和生产环境不同，需要在 config 里区分 - 批量创建发票时，单次上限 100 条，超过会静默截断（不报错） - v2 API 的日期格式是 ISO 8601，但 v1 用的是 Unix 时间戳，混用会导致账单日期错乱 ``` Gotchas 就是你团队的集体记忆。每次 Claude 犯了一个 Skill 范围内的错误，把错误原因追加到 Gotchas 段落，下次就不会再犯。 #### Progressive Disclosure：文件系统即上下文工程 这是 Thariq 文章里我觉得最有洞察力的一个技巧。 Skill 不只是一个 markdown 文件——**它是一个文件夹**。把整个文件系统当作上下文工程和渐进式披露的手段。 ![渐进式披露文件夹结构](/blog/claude-code-skill-design-guide/06-progressive-disclosure.png) Hub-Spoke 模式：SKILL.md 是 hub（中枢），只放触发条件、高级概述和路由表。详细内容放在 spoke 文件里。 ``` billing-lib/ ├── SKILL.md ← hub：一句话描述 + 路由表 ├── gotchas.md ← 踩坑清单 ├── references/ │ ├── api-v2.md ← v2 API 详细文档 │ ├── migration-guide.md ← 从 v1 迁移指南 │ └── examples/ ← 代码示例 ├── scripts/ │ └── validate-invoice.sh ← 辅助脚本 └── config.json ← 运行时配置 ``` 在 SKILL.md 里这样引用： ```markdown ## References Detailed API docs are in `references/api-v2.md`. For migration from v1, see `references/migration-guide.md`. Code examples are in `references/examples/`. ``` Claude 不会一次性把所有文件都读进 context。它会先读 SKILL.md，理解全局结构，然后根据当前任务需要，按需读取具体的 reference 文件。这就是渐进式披露——只在需要的时候加载需要的信息。 #### Don't Railroad：给意图，不给步骤 Claude 会严格遵循指令。如果你写了 Step 1、Step 2、Step 3，Claude 就会一板一眼地执行。但 Skill 是高复用的，不同场景下具体步骤可能不同。 ![过度指令vs给意图](/blog/claude-code-skill-design-guide/05-avoid-railroading.png) **过度指令（railroading）**： ```markdown ## Cherry-pick 流程 Step 1: Run `git fetch origin` Step 2: Run `git checkout -b hotfix/xxx origin/main` Step 3: Run `git cherry-pick ` Step 4: If conflict, open each file and resolve manually Step 5: Run `git push origin hotfix/xxx` ``` **给意图（better）**： ```markdown ## Cherry-pick Cherry-pick the commit onto a clean branch based on the target release. Resolve conflicts preserving the original intent of the change. Push and open a PR targeting the release branch. ``` 第二种写法给了 Claude 足够的灵活空间。如果有冲突，Claude 会根据具体情况决定怎么解决，而不是机械地"open each file"。如果目标分支不是 main，它也能自适应。 #### Store Scripts：让 Claude 组合而非重建 在 Skill 文件夹里放辅助脚本和函数库，让 Claude 花时间在**组合**上，而不是每次都从头写。 ![辅助函数库](/blog/claude-code-skill-design-guide/08-helper-library.jpg) 比如一个数据分析 Skill，可以在 `scripts/` 下放一组基础函数： ```python # scripts/data_helpers.py def fetch_metrics(dashboard_id, time_range): """从 Grafana 获取指标数据""" # ... def compare_cohorts(cohort_a, cohort_b, metric): """对比两个用户群的指标差异""" # ... def format_report(data, template="summary"): """格式化分析报告""" # ... ``` 当用户说"对比上周和本周的注册转化率"时，Claude 不需要从零写数据获取和对比逻辑——它读取已有的 helper 函数，组合出一个新的分析脚本： ![Claude生成的分析脚本](/blog/claude-code-skill-design-guide/09-generated-script.jpg) ```python # Claude 生成的分析脚本 from scripts.data_helpers import fetch_metrics, compare_cohorts, format_report this_week = fetch_metrics("signup-funnel", "7d") last_week = fetch_metrics("signup-funnel", "14d-7d") diff = compare_cohorts(this_week, last_week, "conversion_rate") print(format_report(diff)) ``` 这比每次都从头写 API 调用、数据处理、格式化输出要高效得多。 ### 3.3 持久层：让 Skill 越用越好 #### Memory：跨会话保存数据 Skill 可以通过在文件系统中存储数据来实现记忆。可以简单到一个追加日志，也可以复杂到一个 SQLite 数据库。 ![Memory持久化](/blog/claude-code-skill-design-guide/10-memory-persistence.jpg) 关键点：使用 `${CLAUDE_PLUGIN_DATA}` 作为数据存储路径（Thariq 原文提到的环境变量，实际使用时请参考官方文档确认最新变量名）。这个目录不受 Skill 升级影响，数据可以跨版本保留。 ```markdown ## Memory Append each run's summary to `${CLAUDE_PLUGIN_DATA}/history.log`. Before generating output, read the last 5 entries from history.log to maintain consistency with previous results. ``` standup-post Skill 就是一个好例子：它把每次生成的站会报告保存到日志里，下次运行时 Claude 会读取历史记录，保持风格和格式的一致性。 #### On-Demand Hooks：仅在需要时激活的护栏 Skill 可以注册仅在被调用时才激活的 hooks，持续到会话结束。这比全局 hooks 更精确——你不需要每次都检查是否在操作生产环境，只在真正碰生产时启用保护。 两个实用的例子： **careful hook**——阻止破坏性命令： ```json { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hook": "scripts/careful-check.sh", "description": "Block rm -rf, DROP TABLE, force-push in production context" }] } } ``` **freeze hook**——限制编辑范围： ```json { "hooks": { "PreToolUse": [{ "matcher": "Edit|Write", "hook": "scripts/freeze-check.sh", "description": "Only allow edits within the target directory during debugging" }] } } ``` #### 度量：用 hook 追踪使用情况 用 PreToolUse hook 记录 Skill 被调用的频率、场景、成功率。这些数据能帮你发现哪些 Skill 最热门、哪些从来没被触发过（可能是 description 写得不好）、哪些经常失败（需要加 gotchas）。 --- ## 四、从差 Skill 到好 Skill：可复制的模板 这一章是本文的核心交付物。拿走就能用。 ### 4.1 最小 Skill 目录结构 ``` my-skill/ ├── SKILL.md ← hub：触发条件 + 路由表 + gotchas ├── gotchas.md ← 踩坑清单（内容多时独立出来） ├── references/ ← 详细文档、API 参考、示例代码 │ ├── api.md │ └── examples/ ├── scripts/ ← 辅助脚本和函数库 │ └── helpers.py └── config.json ← 运行时配置（首次使用时生成） ``` 小型 Skill（gotchas 不多时）可以把 gotchas 直接写在 SKILL.md 里，不需要单独文件。 ### 4.2 完整 SKILL.md 模板 ```markdown --- description: | [一句话说明做什么 + 触发词列表] 例：Monitors a PR until it merges. Trigger on 'babysit', 'watch CI', 'make sure this lands'. --- # [Skill 名称] ## What This Does [2-3 句话说明核心功能。不写 Claude 已经知道的常识。] ## Setup Read `config.json` for runtime settings. If config.json is missing, ask the user: - [配置项 1 — 说明] - [配置项 2 — 说明] Save to config.json. ## Gotchas - [踩坑点 1：具体、可验证、来源于实际失败] - [踩坑点 2] - [踩坑点 3] （持续更新。每次发现新问题追加到这里。） ## References - Detailed API docs: `references/api.md` - Code examples: `references/examples/` - Helper scripts: `scripts/` ## Memory Append run summaries to `${CLAUDE_PLUGIN_DATA}/[skill-name]-history.log`. Read last N entries before generating output to maintain consistency. ``` ### 4.3 Description 改写对照表 | 差的写法 | 问题 | 好的写法 | |---------|------|---------| | A comprehensive tool for monitoring PR status across the development lifecycle. | 模糊、无触发词 | Monitors a PR until it merges. Trigger on 'babysit', 'watch CI', 'make sure this lands'. | | Helps with code review and quality assurance. | 太宽泛 | Runs adversarial review on staged changes. Trigger on 'roast my code', 'find bugs', 'review before merge'. | | Database migration management utility. | 像产品说明书 | Creates and runs DB migrations. Trigger on 'new migration', 'add column', 'schema change'. | 规律：**好的 description = 动作 + 触发词**。告诉模型"用户说什么话的时候应该调用我"。 ### 4.4 Gotchas 段落模板 ```markdown ## Gotchas - `amount` 参数单位是分，不是元（1000 = ¥10.00） - 退款接口有 24h 冷却期，重复调用返回 429，不要重试 - 测试环境的 webhook URL 和生产不同，读 config.json 区分 - 批量操作单次上限 100 条，超过会静默截断（不报错不提示） - v2 API 日期格式是 ISO 8601，v1 是 Unix timestamp，混用会导致日期错乱 - 跨时区订单的 created_at 统一用 UTC，展示时需要转换 - 并发创建发票时偶发 duplicate key 错误，加幂等键解决 ``` 每条 gotcha 遵循格式：**现象 + 原因/后果 + 解决方式**（如果简短可以合在一句话里）。 --- ## 五、Skill 设计评估清单 写完一个 Skill 后，对照这份清单检查： **触发层** - [ ] description 包含具体的触发词/短语，不是泛泛的功能描述 - [ ] description 用祈使句开头（动词 + 对象） - [ ] 首次运行有配置引导流程，配置保存到 config.json - [ ] 配置引导优先用结构化选择题，降低用户输入负担 **执行层** - [ ] 没有重复 Claude 已知的常识（React 基础、try-catch 等） - [ ] 有 Gotchas 段落，且来源于实际使用中的失败 - [ ] 使用 hub-spoke 文件结构，SKILL.md 不超过合理长度 - [ ] 详细内容通过 references/ 按需加载，不一次性塞进 context - [ ] 给意图不给步骤，避免 Step 1/2/3 式的过度指令 - [ ] 辅助脚本放在 scripts/，让 Claude 组合复用 **持久层** - [ ] 需要跨会话数据时，使用 `${CLAUDE_PLUGIN_DATA}` 存储 - [ ] 涉及破坏性操作时，配置 On-Demand hooks 做护栏 - [ ] 有度量机制追踪使用频率和失败率 **质量基线** - [ ] SKILL.md 控制在合理篇幅（1500-3000 词，不是越长越好） - [ ] 代码示例可直接运行，不是伪代码 - [ ] 有明确的维护者和更新节奏（谁负责追加 gotchas） --- ## 附录 ### 分发方式 两种路径： 1. **提交到仓库** `.claude/skills/`——适合团队内部使用，版本跟随代码仓库 2. **发布为插件**到 Claude Code 市场——适合跨团队/开源分享 Thariq 提到 Anthropic 内部的市场管理策略是"有机发现"：先放到 sandbox 文件夹，被足够多人使用后再 PR 到正式市场。避免集中审批的瓶颈，但需要策展机制防止劣质或冗余 Skill 堆积。 ### 社区资源 读完这篇，如果想找现成的 Skill 参考或直接复用： - **alirezarezvani/claude-skills**：177+ 个生产级 Skill（测试、调试、Git、安全、数据分析），MIT 协议 - **awesome-claude-code**：策展 Skill、hooks、斜杠命令示例，27k+ stars - **Context Engineering Kit**：13+ 个上下文工程相关 Skill 社区里 @toddsaunders 甚至做了一个"制造 Skill 的 Skill"——自动化采访你的需求、分类类型、起草 SKILL.md、自我审查、生成测试。他说"这让我的 Claude 能力提升了 10 倍"。 @koylanai 在读完 Thariq 的文章后重写了整个 Skills 仓库，"给每个 Skill 都加了 Gotchas 段落"，升级到了 v2.0。 ### 参考来源 Thariq (@trq212), "Skills for Claude Code", X Article, 2026-03-17 https://x.com/trq212/status/2033949937936085378 Anthropic 官方 Claude Code Skills 文档 https://docs.anthropic.com/en/docs/claude-code/skills [从需求到自动化：Claude Code Skill 工具链完整实战](/posts/claude-code-skill-toolchain/) — 本系列前文 --- ## 相关阅读 - [从需求到自动化：Claude Code Skill 工具链完整实战](/posts/claude-code-skill-toolchain/) — 本文讲设计方法论，那篇讲从零搭建 Skill 的完整实战 - [Claude Code 完整安装与配置教程（支持国内模型）](/posts/claude-code-installation/) — 还没装 Claude Code？从这篇开始 - [Claude Code 基础设置](/posts/claude-code-essential-settings/) — 装好之后的必备配置