由 Anthropic Claude Code 团队工程师 Thariq Shihipar 总结的 Skills 实战经验——梳理 Skills 的 9 大类型、编写技巧（踩坑点、渐进式披露、按需 Hooks 等）以及插件市场的分发与管理方式，帮助系统化理解如何创建和推广 Skills。
本文作者 Thariq Shihipar（@trq212）是 Anthropic 的 Claude Code 团队工程师，也是 Skills 功能的核心推动者之一。在加入 Anthropic 之前，他在 MIT Media Lab 读研期间联合创建了开源学术发布平台 PubPub，后来参加了 Y Combinator（W20 批次）。他在 X 上经常分享 Claude Code 的一手使用经验和新功能动态。
这篇文章的价值在于：它是来自 Anthropic 内部团队的实战总结。Anthropic 内部活跃使用的 Skills 已经有几百个，文中的分类体系和编写技巧都是从这些真实的内部实践中提炼出来的。
如果你已经在用 Claude Code 但还没认真做过 Skills，这篇文章能帮你建立一个系统化的思路：做什么类型的 Skills、怎么写、怎么在团队里推广。
背景
Skills 是 Claude Code 中使用最广泛的扩展点之一：灵活、易做、易分发。但正因为灵活，很难判断什么类型的 Skills 值得做、怎么写好、什么时候该分享出去。Anthropic 内部目前活跃使用的 Skills 已有几百个。
核心误解澄清：很多人以为 Skills 只是 markdown 文件，但实际上 Skill 是一个文件夹，可以包含脚本、资源文件、数据等，Agent 可以主动发现、探索和使用这些内容。Claude Code 中的 Skills 还支持丰富的配置项，包括注册动态 hooks。
一、Skills 的 9 大类型
梳理内部所有 Skills 后发现，它们大致落在 9 个反复出现的类别里。好的 Skill 通常清晰属于一类；容易让人困惑的 Skill 往往横跨多类。
1. 库与 API 参考
帮助正确使用某个库 / CLI 工具 / SDK。可针对内部库，也可针对 Claude 容易出错的常用库。通常包含参考代码片段 + 踩坑点清单。
- 示例：内部计费库的边界情况说明；内部 CLI 各子命令用法；帮助 Claude 理解团队设计系统的 frontend-design。
官方博客版本第三个示例为
sandbox-proxy（配置组织的出口网关：哪些主机可访问、如何排查"connection refused"错误、如何加白名单），供参考对照。
2. 产品验证
描述如何测试/验证代码是否正常工作，常配合 Playwright、tmux 等外部工具。值得投入一整周专门打磨。技巧包括：让 Claude 录制操作视频以便复查测试过程；在每一步强制做程序化状态断言。
- 示例：跑通注册→邮箱验证→引导流程并在每步插入断言；用测试卡驱动结账 UI 验证发票状态；针对需要 TTY 的交互式命令行测试。
3. 数据获取与分析
连接数据和监控体系，可能包含带凭证的数据获取库、仪表盘 ID、常用工作流说明。
- 示例：转化漏斗查询要关联哪些事件表；对比两组用户留存/转化差异并标记统计显著性；Grafana 数据源 UID 与问题排查对照表。
4. 业务流程与团队自动化
把重复性工作流压缩成一条命令，指令通常较简单，可能依赖其他 Skills 或 MCP。建议把历史执行结果存日志文件，帮助模型保持一致性。
- 示例：汇总任务系统/GitHub活动/历史Slack消息生成"只报变化"的站会汇报；创建工单时强制字段校验并自动通知审查人；生成周报（合并的PR+关闭的工单+部署记录）。
5. 代码脚手架与模板
为代码库中特定功能生成样板代码，适合搭配脚本使用。当脚手架需求涉及自然语言、难以纯代码覆盖时特别有用。
- 示例：按注解搭建新服务/工作流；数据库迁移文件模板+常见坑点；新建内部应用并预配置认证/日志/部署。
6. 代码质量与审查
执行代码质量标准、辅助代码审查，可包含确定性脚本以保证可靠性，适合作为 hook 自动运行或接入 GitHub Action。
- 示例：让全新视角的子 Agent 挑刺并反复修复迭代（避免原实例思维惯性）；强制执行 Claude 默认容易忽略的代码风格；测试编写指导。
7. CI/CD 与部署
帮助拉取、推送、部署代码，可能引用其他 Skills 收集数据。
- 示例：监控 PR、重试不稳定 CI、解决合并冲突、启用自动合并；构建→冒烟测试→渐进式流量切换并对比错误率，异常时自动回滚；隔离 worktree 中 cherry-pick 并按模板建 PR。
8. 运维手册（Runbook）
接收一个现象（告警/错误特征/Slack消息），引导走完多工具排查流程，产出结构化报告。
- 示例：把现象映射到工具查询模式，覆盖流量最大的服务；拉取告警、检查常见嫌疑点、格式化排查结论；给定请求ID，跨系统拉取匹配日志。
9. 基础设施运维
执行日常维护/运维操作，部分涉及破坏性操作需要安全护栏，帮助工程师在关键操作时遵循最佳实践。
- 示例：找孤立Pod/Volume→发Slack通知→等待→用户确认→级联清理；组织内部依赖审批流程；排查存储/出口带宽费用突增原因。
二、编写 Skills 的技巧
1. 不要说显而易见的事
Claude 对代码库已经很了解，编程能力也不错（包括很多默认判断）。如果 Skill 主要提供知识，重点应放在能打破 Claude 常规思维模式的信息上，而不是重复常识。
例子：Anthropic 的 frontend-design Skill，通过反复迭代打磨出的"设计品味"，专门避免 Inter 字体、紫色渐变这类典型 AI 套路。
2. 建一个"踩坑点"章节
Skill 中信息量最大的部分。应该随着 Claude 实际使用中暴露的失败案例持续积累、更新。
3. 利用文件系统 + 渐进式披露（Progressive Disclosure）
Skill 是文件夹不是单一文件，应把整个文件系统当作"上下文工程"工具：
- 告诉 Claude 有哪些文件，它会按需读取；
- 详细的函数签名/用法示例可拆到
references/api.md； - 最终输出若是 markdown，可在
assets/放模板文件供复制。
4. 不要把 Claude 限制得太死
Skill 复用性强，指令太具体会失去灵活性。应给 Claude 足够信息，同时留出适应具体情况的空间。
5. 考虑好初始设置
有些 Skill 需要用户提供上下文才能完成设置（例如站会机器人要问发到哪个 Slack 频道）。做法：把设置信息存进 Skill 目录下的 config.json；配置缺失时让 Agent 主动询问；如需展示结构化多选题，可用 AskUserQuestion 工具。
6. description 字段是给模型看的，不是摘要
Claude Code 启动会话时会扫描所有 Skill 的描述，判断"这个请求该不该触发这个 Skill"。所以 description 应该描述何时触发，而不是"这个 Skill 做什么"——写法应更接近 if-then 条件语句。
7. 记忆与数据存储
Skill 可以通过内部存储数据实现"记忆"：
- 简单方式：只追加写入的文本日志 / JSON 文件；
- 复杂方式：SQLite 数据库。
- 例：站会 Skill 保留
standups.log，下次运行时读取历史记录，知道"从昨天到现在发生了什么变化"。 - 注意：Skill 目录内的数据在升级 Skill 时可能被清除，应存到稳定目录。官方提供
${CLAUDE_PLUGIN_DATA}作为每个插件的稳定数据存储路径。
8. 存储脚本与生成代码
给 Claude 提供脚本/函数库，让它专注于"组合编排"（决定下一步做什么），而不是重新写样板代码。例如数据科学 Skill 中提供一组数据获取辅助函数，Claude 可即时组合生成脚本回答复杂问题（如"周二发生了什么？"）。
9. 按需 Hooks（On Demand Hooks）
Skill 可以包含只在被调用时才激活、且整个会话期间保持生效的 hooks，适合主观性强、不想常开但偶尔非常有用的场景。
/careful：通过 PreToolUse 拦截rm -rf、DROP TABLE、force-push、kubectl delete等危险命令，仅在明确操作生产环境时开启。/freeze：阻止对指定目录之外任何文件的 Edit/Write，调试时避免误改无关代码。
三、分发 Skills
两种分享方式：
- 提交到代码仓库（
./.claude/skills下）——适合协作仓库较少的小团队，简单直接。 - 做成插件，搭建 Plugin Marketplace——随规模扩大，每个提交的 Skill 都会占用模型上下文，插件市场能让团队成员自行选择安装哪些（官方博客版本还补充：插件市场也可以包含一套安装配置流程）。
管理插件市场
Anthropic 内部没有专门中心团队审核，倾向让最有用的 Skill 自然涌现：
- 先上传到 GitHub 的沙盒文件夹，在 Slack/论坛推荐；
- 获得足够关注后（由作者自行判断），提交 PR 移入正式插件市场；
- 提醒：低质量/重复 Skill 很容易产生，发布前需要某种审核机制。
组合 Skills
Skill 之间可以互相依赖（例如文件上传 Skill + CSV 生成 Skill）。目前插件市场/Skill 机制本身不支持正式的依赖管理，但可以直接在一个 Skill 中按名字引用另一个 Skill，只要对方已安装，模型会自动调用。
衡量 Skills 效果
用 PreToolUse hook 在公司内部记录 Skill 使用情况（原文附有示例代码 gist），从而发现哪些 Skill 受欢迎、哪些触发频率低于预期。
结语要点
- Skills 仍处于早期阶段，最佳实践仍在摸索中；
- 这篇文章更像是"实践中验证有效的技巧合集"，而非权威指南；
- 理解 Skills 最好的方式是动手实践、不断试验；
- 多数 Skill 起步都很简单（几行文字 + 一个踩坑点），随着团队不断补充边界情况才逐渐完善。
本笔记为内容整理，非原文逐字翻译。完整原文（含配图）请见：
评论交流
支持作者