Skills 已成为 Claude Code 里用得最多的扩展点之一：灵活、好做、好分发。

但这种灵活也让人难判断什么最好用。什么样的 Skills 值得做？怎么组织一个 Skill？何时与他人分享？

我们在 Anthropic 大量使用 Claude Code 的 Skills，活跃中的有数百个。下面是用 Skills 加速开发时学到的经验。

Skills 是什么？

Skills 是装有说明、脚本与资源的文件夹，Agent 可发现并用它们把事做得更准、更高效。本文假定你已熟悉 Skills 基础；若是新手，先看 Skilljar 上的 Introduction to agent skills 课程。

常见误解是 Skills「只是 markdown 文件」。它们其实是文件夹，可含脚本、资产、数据等，供 Agent 发现、探索与操作。

在 Claude Code 里，Skills 还有 多种配置选项，包括注册动态 hooks。

我们发现，Claude Code 里最有效的 Skills，往往把这些配置与文件夹结构用好了。

Skills 的类型

盘点 Anthropic 内部全部 Skills 后，我们发现它们可聚成九类。最好的 Skills 干净落在一类；试图做太多的会跨好几类，把 Agent 搞糊涂。这不是终极清单，但是找自家 Skills 库缺口的有用框架。

A three-by-three grid of skill categories with example skill names: Library and API Reference, Product Verification, Data and Analysis, Business Automation, Scaffolding and Templates, Code Quality and Review, CI/CD and Deployment, Incident Runbooks, Infrastructure Ops.

Claude Code 团队把内部 Skills 归类后发现，可装进九个分明的桶。

1. 库与 API 参考

说明如何正确使用某个库、CLI 或 SDK。可以是内部库，也可以是 Claude Code 有时搞不定的常见库。这类 Skills 常带一文件夹参考代码片段，以及 Claude 写脚本时要避开的坑列表。

例如：

  • billing-lib — 内部计费库：边界情况、易踩坑等
  • internal-platform-cli — 内部 CLI 包装的每个子命令，及何时用的示例
  • sandbox-proxy — 配置组织的 egress 网关做开发：哪些 host 可达、如何调试「connection refused」、如何加 allowlist

2. 产品验证

描述如何测试或验证代码是否工作。常与 playwright、tmux 或其他外部验证工具配对。

验证类 Skills 对我们内部 Claude 输出质量的可测影响最大。值得让工程师花一周把验证 Skills 做到极致。

可考虑让 Claude 录制输出视频，好看到它到底测了什么；或在每步对状态做程序化断言。这些往往靠在 Skill 里放各种脚本完成。

例如：

  • signup-flow-driver — 在无头浏览器里走完 signup → 邮件验证 → onboarding，每步有断言状态的 hooks
  • checkout-verifier — 用 Stripe 测试卡驱动结账 UI，验证发票真落到正确状态
  • tmux-cli-driver — 交互式 CLI 测试，被验证对象需要 TTY

3. 数据拉取与分析

接到数据与监控栈的 Skills。可能含带凭证的取数库、具体 dashboard id 等，以及常见工作流或取数方式说明。

例如：

  • funnel-query — 「看 signup → activation → paid 要 join 哪些事件」，以及真正有规范 user_id 的那张表
  • cohort-compare — 比较两 cohort 留存或转化，标出统计显著差，链到分段定义
  • grafana — datasource UID、集群名、问题 → dashboard 查找表
  • datadog — 字段参考（@request_id vs trace_id）、服务列表、指标前缀约定

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

把重复工作流收成一条命令。说明往往简单，但可能更复杂地依赖其他 Skills 或 MCP。对这类 Skills，把以往结果存进日志文件，有助于模型保持一致并反思过往执行。

例如：

  • standup-post — 汇总 ticket 跟踪器、GitHub 活动与先前 Slack → 格式化 standup，只出增量
  • create-<ticket-system>-ticket — 强制 schema（合法枚举、必填字段）加创建后工作流（@审阅者、链到 Slack）
  • weekly-recap — 已合并 PR + 已关 ticket + 部署 → 格式化回顾帖

5. 代码脚手架与模板

为代码库里某类功能生成框架样板。可与可组合脚本搭配。脚手架有自然语言要求、纯代码盖不住时特别有用。

例如：

  • new-<framework>-workflow — 用你们的注解脚手架新服务/工作流/handler
  • new-migration — 迁移文件模板加常见坑
  • create-app — 新内部 App，预接好鉴权、日志与部署配置

6. 代码质量与审查

在组织内强制代码质量、帮助审代码。可含确定性脚本或工具以求稳健。可在 hooks 或 GitHub Action 里自动跑。

  • adversarial-review — 拉起 fresh-eyes subagent 批评，落实修复，迭代到发现降成吹毛求疵
  • code-style — 强制代码风格，尤其 Claude 默认做得不好的那些
  • testing-practices — 怎么写测试、测什么

7. CI/CD 与部署

帮你在代码库里取、推、部署代码。可能引用其他 Skills 收集数据。

例如：

  • babysit-pr — 监控 PR → 重试 flaky CI → 解合并冲突 → 开 auto-merge
  • deploy-<service> — 构建 → smoke test → 按错误率对比逐步放量 → 回归时自动回滚
  • cherry-pick-prod — 隔离 worktree → cherry-pick → 解冲突 → 带模板开 PR

8. Runbooks

从症状（Slack 线程、告警、错误签名）出发，走多工具调查，产出结构化报告。

例如：

  • <service>-debugging — 为最高流量服务映射症状 → 工具 → 查询模式
  • oncall-runner — 拉告警 → 查常见嫌疑人 → 格式化发现
  • log-correlator — 给定 request ID，从可能碰过它的每个系统拉匹配日志

9. 基础设施运维

做例行维护与运维流程，有些含破坏性操作、需要护栏。让工程师在关键操作上更容易遵循最佳实践。

例如：

  • <resource>-orphans — 找孤儿 pod/volume → 发到 Slack → 浸泡期 → 用户确认 → 级联清理
  • dependency-management — 组织的依赖审批工作流
  • cost-investigation — 「为什么存储/出口账单飙了」，带具体 bucket 与查询模式

做 Skills 的技巧

定了要做什么 Skill，怎么写？下面是 Claude Code 团队的若干最佳实践与技巧。

别写显而易见的

Claude 已经会写代码，也能读你的代码库。只是复述 Claude 默认就会做的事，只会加上下文不加价值。若发的 Skill 主要是知识，聚焦那些能把 Claude 推出惯常思路的信息。

frontend design Skill 是好例子：Anthropic 一位工程师与客户迭代，提升 Claude 的设计品味，避开 Inter 字体和紫色渐变这类经典套路。

建 Gotchas 小节

The same Billing Lib skill file on day 1, week 2 and month 3. A Gotchas section appears and grows from one line (proration rounds down) to four.

任何 Skill 里信号最强的内容是 Gotchas 小节。应基于 Claude 用你的 Skill 时常见失败点积累。理想情况是随时间更新 Skill，把这些坑收进去。

例如：

  • 「subscriptions 表只追加。你要的行是 version 最高的那条，不是 created_at 最新的。」
  • 「这字段在 API 网关叫 @request_id，在计费服务叫 trace_id。值相同。」
  • 「Staging 在 Stripe webhook 其实没处理时仍返回 200。真状态看 payment_events。」

用文件系统与渐进披露

A queue-debugging skill folder where SKILL.md is the hub and stuck-jobs.md, dead-letters.md, retry-storms.md and consumer-lag.md are spokes. SKILL.md holds a symptom-to-file table telling Claude which file to read.

SKILL.md 指向若干其他文件，供 Claude 在特定情况引用。例如任务 pending 时应看 stuck-jobs.md。

如前所述，Skill 是文件夹，不只是 markdown。应把整个文件系统想成一种 上下文工程与渐进披露。告诉 Claude Skill 里有哪些文件，它会在合适时机去读。

最简单的渐进披露是指向其他 markdown。例如把详细函数签名与用法示例拆到 references/api.md。

又如：若最终输出是 markdown，可在 assets/ 放模板文件供复制使用。

可以有 references、scripts、examples 等文件夹，帮 Claude 更高效工作。

避免把 Claude 锁死在轨道上

Claude 一般会尽量守你的说明；Skills 可高度复用，因此说明里不宜太死。给它需要的信息，同时留出适应情境的灵活度。

例如：

Two versions of cherry-pick instructions. Too prescriptive: six numbered steps spelling out each git command. Better: “Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can’t land cleanly, explain why.”

写目标和约束，不要写死每一步。

想清楚 setup

A standup-post SKILL.md whose “Your config” section runs a shell command reading config.json and echoing NOT_CONFIGURED if it is missing; the instructions tell Claude to ask for the Slack channel and a sample standup when unconfigured, then save the answers.

上面的 Skill 写成：若配置里没有 Slack 频道，就提示用户。

有些 Skills 需要用户提供上下文才能 setup。例如发 standup 到 Slack 的 Skill，可能要 Claude 问发到哪个频道。

好模式是把 setup 信息存进 Skill 目录的 config.json，如上例。若未配置，Agent 再向用户要信息。

若要结构化多选问题，可指示 Claude 用 AskUserQuestion 工具。

描述写给模型，不是给人

Claude Code 开会话时会建一份所有可用 Skill 及其描述的列表。Claude 扫这份列表来决定「有没有适合这个请求的 Skill？」因此 description 字段不是摘要，而是 何时触发该 Skill 的描述。

Two SKILL.md descriptions for babysit-pr. Left: “A comprehensive tool for monitoring pull request status across the development lifecycle.” Right: “Monitors a PR until it merges. Trigger on ‘babysit’, ‘watch CI’, ‘make sure this lands’.”

在描述里写上触发词，如「babysit」，会有帮助。

帮 Claude 记住

A ~/.claude/standups.log file with dated entries for three consecutive days; the onboarding redesign thread is highlighted across all of them.

这份文本日志帮 Claude 记住过去事件，如审过 Sarah 的 auth PR。

有些 Skills 可通过在内部存数据形成记忆。可以简单到只追加的文本日志或 JSON，也可以复杂到 SQLite。

例如 standup-post Skill 可保留 standups.log，记下每次写过的帖；下次再跑时 Claude 读自己的历史，能看出相对昨天变了什么。

可用环境变量 ${CLAUDE_PLUGIN_DATA} 拿到稳定目录存数据，详见 Skills 持久数据：https://code.claude.com/docs/en/plugins-reference#persistent-data-directory。

存脚本并生成代码

能给 Claude 的最强工具之一是代码。给它脚本和库，让它把回合花在组合上——决定下一步做什么，而不是重构样板。

例如在 data-science Skill 里可有一套从事件源取数的函数库。为让 Claude 做复杂分析，可给一组辅助函数：

lib/signups.py with three helper functions, fetch, by_referrer and by_landing_page, whose docstrings record data gotchas such as user_id being null until after signup.

给 Claude 一小库 helpers，把坑写进 docstring。

Claude 就能现场生成脚本组合这些能力，做更高级分析，例如对提示「星期二发生了什么？」

investigate.py, generated by Claude, importing those helpers to compare Monday and Tuesday signups by referrer and landing page and concluding that something broke on the homepage on Tuesday.

Claude 把 helpers 组合成针对当前问题的一次性脚本。

用按需 hooks

Skills 可含仅在调用 Skill 时激活、且只在本会话持续的 hooks。用于更有观点、不想常开、但有时极有用的 hooks。

例如：

  • /careful — 经 Bash 的 PreToolUse matcher 拦住 rm -rf、DROP TABLE、force-push、kubectl delete。只在知道要碰生产时开——一直开会疯。
  • /freeze — 拦住不在特定目录的 Edit/Write。调试时有用：「我想加日志，却老『修』无关代码。」

分发 Skills

Skills 的一大好处是能与团队分享。

与他人分享大致有两种方式：

  • 把 Skills 检入仓库（在 ./.claude/skills 下）
  • 做成 plugin，并有 Claude Code Plugin marketplace 供上传安装（见 文档）

小团队、仓库不多时，检入仓库就够。但每个检入的 Skill 也会给模型上下文加点负担。规模上去后，内部 plugin marketplace 可分发 Skills，让团队自己决定装哪些，并带 setup 流程。

管理 Skills marketplace

哪些 Skills 进 marketplace？怎么提交？

在 Anthropic，没有中央团队拍板；我们试着有机发现最有用的。若有人想让大家试用某个 Skill，可上传到 GitHub 的 sandbox 文件夹，在 Slack 等论坛指向它。

Skill 有了 traction（由 Skill 所有者判断）后，可提 PR 移入 marketplace。

组合 Skills

可能希望 Skills 互相依赖。例如有一个上传文件的 Skill，和一个生成 CSV 再上传的 Skill。这类依赖管理尚未原生进 marketplace 或 Skills，但可以按名引用其他 Skills，若已安装，模型会调用。

度量 Skills

为了解 Skill 表现，我们用 PreToolUse hook 在公司内记录 Skill 使用（示例代码）。这样能找到热门 Skills，或相对预期触发偏少的。

开始动手

Skills 最佳实践仍在演进。我们最好的 Skills 多数从几行字和一个 gotcha 起步，再因 Claude 撞上新边界情况、大家不断补充而变好。

理解 Skills 最好的办法是动手、实验，看什么对你管用。

本文作者 Thariq Shihipar，Anthropic Member of Technical Staff，负责 Claude Code。