Skills 已经成为 Claude Code 中使用最频繁的扩展点之一。由于制作和分发门槛较低，它们在 Anthropic 内部被广泛用于加速开发，目前活跃使用的 Skill 已经达到数百个。本文基于这些内部实践，总结了常见 Skill 类型以及在编写、维护和团队分发过程中的经验。

Skills 的定位

官方文档和课程对 Skills 的基础概念已有系统介绍。Anthropic 在内部使用中发现，一个常见误解是把 Skills 视作“只是一个 markdown 文件”。实际上，Skill 是一个文件夹，可以包含脚本、资源文件、数据等多种内容，Claude 可以在执行任务时主动发现并调用这些文件。

在 Claude Code 中，Skills 还可以通过 frontmatter 配置丰富的选项，包括注册动态钩子（hooks）。许多效果最好的 Skills，正是充分利用了这些配置能力和文件夹结构。

对内部大量 Skills 进行梳理后，团队发现它们大致可以归纳为若干反复出现的类型。清晰聚焦于某一类型的 Skills 通常更易理解和复用，而跨越多个用途的 Skills 更容易让使用者困惑。以下分类并非穷尽，但可作为团队自查 Skill 体系是否完整的参考框架。

九类常见 Skill 场景

skills-types

1. 库与 API 参考

这类 Skills 用于帮助 Claude 正确使用某个库、命令行工具或 SDK，既可以面向内部库，也可以针对 Claude 偶尔会出错的常用开源库。典型内容包括：

  • 参考代码片段集合
  • 常见边界情况与“踩坑点”（gotchas）列表

示例：

  • billing-lib：内部计费库的使用说明、边界情况和容易出错的模式
  • internal-platform-cli：内部 CLI 工具的子命令说明及使用场景示例
  • frontend-design：帮助 Claude 理解团队的前端设计系统

2. 产品验证

这类 Skills 描述如何验证某段代码或某个功能是否按预期工作，通常会结合 Playwright、tmux 等外部工具执行自动化验证。

验证类 Skills 对提升 Claude 输出的可靠性作用明显。Anthropic 的实践表明，投入专门工程师集中打磨一批验证 Skills，回报较高。

常见做法包括：

  • 通过脚本录制验证过程，便于回溯 Claude 实际执行了哪些步骤
  • 在关键步骤加入程序化状态断言

示例：

  • signup-flow-driver：在无头浏览器中跑完注册、邮件验证和引导流程，并在每一步插入状态检查
  • checkout-verifier：使用 Stripe 测试卡驱动结账流程，验证发票最终状态
  • tmux-cli-driver：支持需要 TTY 的交互式命令行测试

3. 数据获取与分析

这类 Skills 负责连接内部数据和监控系统，封装常用查询方式和分析流程，可能包含：

  • 带凭证的数据访问库
  • 常用仪表盘 ID 和数据源标识
  • 典型分析工作流说明

示例：

  • funnel-query：说明注册→激活→付费转化分析需要关联的事件和表
  • cohort-compare：对比不同用户群的留存或转化率，并标记统计显著差异
  • grafana：记录数据源 UID、集群名称以及问题与仪表盘的对应关系

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

这类 Skills 将重复性团队工作流封装为一条命令，常见特点是：

  • 指令本身较简单
  • 可能依赖其他 Skills 或 MCP
  • 会在本地记录执行日志，便于 Claude 参考历史行为保持一致性

示例：

  • standup-post：汇总任务追踪器、GitHub 活动和 Slack 消息，生成只包含增量信息的站会汇报
  • create--ticket：按统一 schema 创建工单，并触发后续通知和流转
  • weekly-recap：基于已合并 PR、已关闭工单和部署记录生成周报

5. 代码脚手架与模板

这类 Skills 用于为特定类型的功能生成样板代码，尤其适合那些既依赖代码结构又包含自然语言约定的场景。

示例：

  • new--workflow：根据注解搭建新的服务、工作流或处理器
  • new-migration：生成数据库迁移文件模板并附带常见注意事项
  • create-app：创建新内部应用，并预配置认证、日志和部署设置

6. 代码质量与审查

这类 Skills 用于在团队内部统一代码质量标准，并辅助代码审查。通常会结合确定性的脚本或工具，以提高可靠性，可作为钩子自动运行，也可以集成到 GitHub Actions 中。

示例：

  • adversarial-review：启动一个全新子智能体从“陌生视角”审查代码，提出问题并驱动修复，反复迭代直至问题收敛
  • code-style：强制执行团队约定的代码风格，覆盖 Claude 默认不擅长的部分
  • testing-practices：提供如何编写测试以及测试重点的指导

7. CI/CD 与部署

这类 Skills 负责拉取、推送和部署代码，可能会调用其他 Skills 收集上下文信息。

示例：

  • babysit-pr：监控某个 PR，重试不稳定的 CI 任务，解决合并冲突并启用自动合并
  • deploy-：构建、冒烟测试、渐进式流量切换并对比错误率，在指标恶化时自动回滚
  • cherry-pick-prod：在隔离 worktree 中 cherry-pick、解决冲突并按模板创建 PR

8. 运维手册

这类 Skills 从一个现象出发（如 Slack 告警消息或错误特征），引导完成多工具排查，并输出结构化报告。

示例：

  • -debugging：将现象映射到具体工具和查询模式，覆盖流量最大的服务
  • oncall-runner：拉取告警、检查常见原因并输出排查结论
  • log-correlator：基于请求 ID 从各个系统中收集关联日志

9. 基础设施运维

这类 Skills 用于执行日常维护和运维操作，其中部分操作具有破坏性，需要配套安全机制。通过 Skill 固化流程，可以帮助工程师在关键操作中更好地遵循既定规范。

示例：

  • -orphans：查找孤立 Pod/Volume，推送到 Slack 观察并在确认后执行级联清理
  • dependency-management：封装组织内部的依赖审批流程
  • cost-investigation：排查存储或出口带宽费用异常增长，并关联到具体资源和查询模式

编写 Skills 的实践经验

skill-writing

在明确 Skill 类型之后，如何具体落地？Anthropic 在内部总结出一系列可复用的写作和设计技巧。与此同时，官方也推出了 Skill Creator，帮助用户在 Claude Code 中更便捷地创建和迭代 Skills。

聚焦“非常识”信息

Claude 对通用编程知识和代码库本身已有较强理解。对于以知识传递为主的 Skills，更有价值的是那些能纠正模型默认倾向、打破常规模式的信息，而不是重复显而易见的内容。

例如，frontend-design Skill 就是通过与用户反复迭代，专门针对团队的设计偏好进行调校，刻意规避模型常见的默认风格。

单独维护“踩坑点”章节

gotchas

实践表明，Skill 中信息密度最高的部分往往是“踩坑点”章节。建议根据 Claude 在实际使用中暴露出的失败模式持续补充这一部分，并将其作为长期维护重点。

利用文件系统做“渐进式披露”

fs-context

Skill 是一个目录而非单一文件，可以将其视作上下文工程和渐进式披露的载体。通过在 SKILL 描述中点名目录结构，让 Claude 在需要时再去读取具体文件，可以节省上下文窗口并提高信息利用效率。

常见做法包括：

  • 将详细函数签名和用法示例拆分到 references/api.md
  • 在 assets/ 中放置可复制的输出模板
  • 按用途划分 references/、scripts/、examples/ 等子目录

保留适度灵活性

Claude 会尽量遵循 Skill 中的指令。由于 Skills 往往被复用在多种场景，过于具体的约束可能降低泛化能力。建议在提供关键信息的同时，避免对执行细节做过度限定，让模型可以根据上下文调整策略。

flexibility

设计好初始配置流程

config

部分 Skills 在首次使用时需要用户提供额外上下文，例如：

  • 站会汇报要发送到哪个 Slack 频道
  • 默认使用哪个项目或环境

常见做法是将这些配置写入 Skill 目录下的 config.json。如果配置缺失，Claude 会主动向用户询问。若需要展示结构化多选项，可通过 AskUserQuestion 工具实现。

正确认识 description 字段

当 Claude Code 启动会话时，会先构建一份可用 Skills 及其 description 的清单，并据此判断是否需要调用某个 Skill。因此，description 字段的核心作用是告诉模型“在什么情况下应该触发这个 Skill”，而不是简单的功能摘要。

一个有效的 description 更接近 if-then 条件描述，而非营销式介绍。

description

记忆与数据存储

memory

部分 Skills 可以通过内部数据存储实现“记忆”能力，常见方式包括：

  • 只追加写入的文本日志或 JSON 文件
  • 使用 SQLite 等轻量数据库

例如，standup-post Skill 可以维护一个 standups.log，记录每次生成的站会内容。下次运行时，Claude 读取该日志即可只汇报自上次以来的变化。

需要注意的是，Skill 目录本身在升级时可能被替换，因此数据应存放在稳定路径。目前 Claude Code 提供了 ${CLAUDE_PLUGIN_DATA} 作为每个插件的持久化数据目录。

利用脚本与生成代码

给 Claude 提供可复用的脚本和库，可以显著提升 Skill 的能力上限。模型可以在此基础上专注于“如何组合这些能力”，而不是从零编写样板代码。

在数据分析类 Skills 中，常见做法是：

  • 提供一组从事件源获取数据的函数
  • 提供若干辅助函数，支持更复杂的统计和可视化

helpers

在此基础上，Claude 可以即时生成脚本，回答诸如“某一天发生了什么变化”之类的问题。

analysis

按需启用的钩子

Skills 可以携带“按需钩子”（On Demand Hooks）：只有在该 Skill 被调用时才会注册，并在整个会话期间生效。这类钩子适合那些主观性较强、并不希望长期开启但在特定场景非常有用的规则。

示例：

  • /careful：通过 PreToolUse 钩子拦截 Bash 中的 rm -rf、DROP TABLE、force-push、kubectl delete 等高风险操作，适合在明确操作生产环境时临时启用
  • /freeze：阻止对指定目录之外的任何 Edit/Write 操作，便于在调试时只修改目标区域

团队分发与治理

Skills 的一大优势在于可以在团队内部共享。常见分发方式有两种：

  1. 将 Skills 直接提交到代码仓库（例如放在 ./.claude/skills 目录）
  2. 封装为插件，通过内部 Claude Code 插件市场（Plugin Marketplace）供用户按需安装

对于协作仓库数量有限的小团队，将 Skills 随代码一同管理通常足够。但每新增一个仓库级 Skill，都会在一定程度上增加模型的上下文负担。随着规模扩大，内部插件市场可以在“集中分发”和“按需安装”之间取得平衡。

插件市场的管理方式

在 Anthropic 内部，并没有专门的中心团队统一决定哪些 Skills 可以进入插件市场，而是鼓励有用的 Skills 自然涌现：

  • 作者先将 Skill 上传到 GitHub 的沙盒目录
  • 通过 Slack 等渠道邀请同事试用
  • 当使用反馈和关注度达到一定程度后，再由作者发起 PR，将 Skill 移入正式插件市场

由于创建质量一般或功能重复的 Skills 成本很低，实践中通常会在正式发布前设置一定的审核流程。

Skills 之间的组合

在实际使用中，团队往往希望 Skills 能互相调用。例如：

  • 一个文件上传 Skill
  • 一个生成 CSV 并上传的 Skill

目前插件市场和 Skills 本身尚未提供显式依赖管理机制，但可以在 Skill 中直接按名称引用其他 Skills。只要目标 Skill 已安装，Claude 就可以在执行时调用它们。

评估 Skills 的效果

为了了解某个 Skill 的实际表现，Anthropic 使用了 PreToolUse 钩子记录内部 Skill 的调用情况（相关示例代码已公开）。通过这些数据，可以观察：

  • 哪些 Skills 使用频率较高
  • 哪些 Skills 触发率低于预期，可能需要改进描述或功能

结语

在 Anthropic 的实践中，Skills 已经成为构建 AI 智能体能力的重要基础设施之一。但整体仍处于早期阶段，最佳实践还在不断演化。

本文并非权威规范，而是基于内部大规模使用 Claude Code 的一组经验汇总。团队在实际工作中通常从一个简单的 Skill 开始——也许只是几行说明和一个“踩坑点”列表——再随着使用过程不断补充新的边界情况和脚本，逐步打磨成熟。

理解和用好 Skills 的最直接方式，仍然是尽早动手实践、持续试验，并根据团队的真实需求迭代。