今天这篇文章，推荐给所有正在关注 Claude Code、也想把 Agent 工作流做深的人。作者 Thariq Shihipar（@trq212）目前在 Anthropic 参与 Claude Code 相关工作，本身就是一线建设者。这篇文章谈的，也不是抽象理念，而是他们在内部把 Skills 真正用起来之后沉淀出的经验。
按照作者的说法，Anthropic 内部已经有数百个 Skills 在活跃使用，所以你会发现，文中讲的不是“Skill 是什么”这种入门问题，而是更重要的几件事：Skills 应该怎么分类、怎么写得更稳、怎么在团队里分发，以及怎么避免它们越做越乱。对于已经开始接触 Agent 工程的人来说，这类一手经验，往往比单纯的产品文档更有价值。
以下是全文翻译，原始文章链接（https://x.com/trq212/status/2033949937936085378），Happy Reading！
Skills 已成为 Claude Code 中使用最广泛的扩展之一，其足够灵活，制作门槛低，便于分发。
但也正因这种灵活性，人们反而很难判断，到底什么样的 skill 值得做？写好一个 skill 的诀窍是什么，又该在什么时机把它分享给别人？
在 Anthropic 内部，我们已经在 Claude Code 中大规模使用 skills，目前有数百个skill 处于活跃使用状态。以下是我们在用 skills 加速开发过程中总结出的经验。
什么是 Skills？
如你刚接触 skills，我建议先阅读我们的 docs，或者观看我们最新的 Agent Skills Skilljar 课程；本文默认你已经对 skills 有一定了解。
经常听到一种误解：有人认为 skills “不过是 markdown 文件”。
实际上，skills 最有意思的地方恰在于，它们不只是文本文件。它们是一个文件夹，里面可以包含 scripts、assets、data 等等，而 agent 可以发现、浏览并操作这些内容。
在 Claude Code 中，skills 还支持大量 configuration options，包括注册动态 hooks。
我们发现，Claude Code 中一些最有意思的 skill，正是创造性地利用了这些 configuration options 与文件夹结构。
Skills 的类型
在梳理内部所有 skills 后，我们发现它们大致会聚集到几个反复出现的类别中。最好的 skill 往往能够清晰归入某一个类别；而那些让人困惑的 skill，通常是横跨了多个类别。这不是一份穷尽式清单，但它很适合作为一个思考框架，帮助你判断自己的组织里是否缺少某些类型的 skill。
1-库与 API 参考
这类 skill 用来说明：如何正确使用某个库、CLI 或 SDK。它既可以面向内部库，也可以面向那些 Claude Code 偶尔掌握得不够稳妥的常见库。这类 skill 往往会附带一个参考代码片段目录，以及一份“易踩坑事项（gotchas）”清单，帮助 Claude 在编写脚本时避开常见错误。
示例：
• billing-lib—— 你的内部计费库：包括边界情况、隐蔽坑点等• internal-platform-cli—— 你的内部 CLI 封装器的全部子命令，以及各自适用场景的示例• frontend-design—— 帮助 Claude 更好地遵循你的设计系统（design system）
2-产品验证
这类 skill 用来描述：如何测试或验证你的代码是否真的正常工作。它们通常会与外部工具搭配使用，比如 Playwright、tmux 等，以完成验证过程。
验证类 skill 对于确保 Claude 的输出正确，价值极高。很多时候，专门让一位工程师花上一周时间，把验证类 skill 打磨到足够优秀，是非常值得的。
你可以考虑采用这样的技巧：让 Claude 录下它输出过程的视频，这样你就能准确看到它究竟测试了什么；或者在每一步都加入可程序化检查的状态断言（assertions）。这类能力通常通过在 skill 中加入多种脚本来实现。
示例：
• signup-flow-driver—— 在无头浏览器（headless browser）中完整跑通“注册 → 邮箱验证 → 新手引导”流程，并在每一步提供状态断言 hooks• checkout-verifier—— 使用 Stripe 测试卡驱动结账界面，并验证 invoice 是否真的进入了正确状态• tmux-cli-driver—— 用于交互式 CLI 测试，适合那些被验证对象必须运行在 TTY 环境中的场景
3-数据获取与分析
这类 skill 负责连接你的数据体系与监控体系。它们可能包含用于携带凭证获取数据的库、特定 dashboard 的 id，以及常见工作流说明或获取数据的标准方法。
示例：
• funnel-query—— 说明“若要查看 signup → activation → paid，需要关联哪些事件”，以及真正保存规范user_id的那张表• cohort-compare—— 比较两个 cohort 的留存或转化，标出具有统计显著性的差异，并链接到对应的 segment 定义• grafana—— 提供数据源 UID、集群名称，以及“问题 → dashboard”的查询映射表
4-业务流程与团队自动化
这类 skill 会把重复性的工作流自动化为一条命令。它们通常只是相对简单的指令集合，但有时也可能依赖其他 skills 或 MCP。对于这一类 skill，把之前执行的结果保存到日志文件中，往往能帮助模型保持前后一致，并回顾这个工作流过去是如何执行的。
示例：
• standup-post—— 汇总你的工单跟踪器、GitHub 活动以及此前的 Slack 内容，生成格式化的 standup，只输出增量变化• create-<ticket-system>-ticket—— 强制执行 schema 约束（如合法枚举值、必填字段），并完成建单后的后续流程（提醒 reviewer、把链接贴到 Slack）• weekly-recap—— 将已合并的 PR、已关闭的工单以及部署记录汇总成格式化的周报帖
5-代码脚手架与模板
这类 skill 用于为代码库中的某类特定功能生成框架样板代码（boilerplate）。你也可以把它与可组合的脚本搭配使用。当你的脚手架不仅仅是代码模板，还包含一些无法单纯靠代码表达的自然语言要求时，这类 skill 尤其有用。
示例：
• new-<framework>-workflow—— 按照你的注解规范，为新的 service / workflow / handler 生成脚手架• new-migration—— 你的 migration 文件模板，以及常见易踩坑事项• create-app—— 创建一个新的内部应用，并预先接好认证（auth）、日志（logging）和部署配置（deploy config）
6-代码质量与评审
这类 skill 用来在组织内部落实代码质量要求，并辅助开展代码评审。为了获得更高的稳健性，它们可以包含确定性的脚本或工具。你也可以考虑把这些 skill 作为 hooks 的一部分自动运行，或者放进 GitHub Action 中执行。
示例：
• adversarial-review—— 拉起一个拥有“新鲜视角”的子 agent 来挑刺、实施修复，并持续迭代，直到问题退化为吹毛求疵式的小瑕疵• code-style—— 强制执行代码风格规范，尤其适用于那些 Claude 默认做得不够好的风格要求• testing-practices—— 说明测试应当如何编写，以及究竟该测试什么
7-CI/CD 与部署
这类 skill 帮助你在代码库中完成拉取、推送与部署等操作。它们也可能引用其他 skills，以收集所需的数据。
示例：
• babysit-pr—— 监控一个 PR → 重试不稳定的 CI → 解决合并冲突 → 开启自动合并• deploy-<service>—— 构建 → 冒烟测试（smoke test）→ 逐步放量上线，并比较错误率 → 一旦出现回归则自动回滚• cherry-pick-prod—— 创建隔离的 worktree → 执行 cherry-pick → 解决冲突 → 按模板发起 PR
8-处置手册（Runbooks）
这类 skill 从某个症状出发——例如一条 Slack 讨论串、一个告警，或者某种错误特征——引导你完成一条跨工具的排查链路，并最终生成结构化报告。
示例：
• <service>-debugging—— 为高流量服务建立“症状 → 工具 → 查询模式”的映射关系• oncall-runner—— 拉取告警 → 检查常见嫌疑项 → 输出格式化的结论• log-correlator—— 给定一个 request ID，从所有可能接触过该请求的系统中拉取匹配日志
9-基础设施运维
这类 skill 用来执行日常维护与运维操作，其中有些操作具有破坏性，因此特别适合配上安全护栏（guardrails）。它们能让工程师在关键操作中更容易遵循最佳实践。
示例：
• <resource>-orphans—— 找出孤立的 pods / volumes → 发到 Slack → 经过一段观察期（soak period）→ 用户确认 → 级联清理• dependency-management—— 你所在组织的依赖审批工作流• cost-investigation—— 调查“为什么我们的存储 / 出网流量账单突然飙升”，并给出对应的 buckets 与查询模式
制作 Skills 的建议
当你已经决定要做哪个 skill 之后，接下来该怎么写？下面这些，是我们总结出来的一些最佳实践、技巧与经验。
我们最近也更新了 Skill Creator，让在 Claude Code 中创建 skills 变得更容易。
1-不要陈述显而易见的内容
Claude Code 对你的代码库已经知道很多，而 Claude 对编程本身也掌握了大量知识，并且自带不少默认判断。因此，如果你发布的是一个以知识为主的 skill，就应尽量把重点放在那些能打破 Claude 常规思维模式的信息上。
frontend-design 这个 skill 就是一个很好的例子。它由 Anthropic 的一位工程师在与客户不断迭代的过程中打磨出来，目标是提升 Claude 的设计品味，并帮助它避开一些经典套路，例如 Inter 字体和紫色渐变。
2-建立一个“易踩坑事项”
任何一个 skill 中，信号最强、最有价值的内容，往往就是 Gotchas（易踩坑事项） 这一部分。这个部分应当围绕 Claude 在使用该 skill 时反复撞上的常见失败点来持续积累。理想情况下，你会随着时间推移不断更新 skill，把这些新发现的坑点补充进去。
3-善用文件系统与渐进式披露
正如前面所说，skill 是一个文件夹，而不只是一个 markdown 文件。你应该把整个文件系统都视为上下文工程与渐进式披露的一部分。只要告诉 Claude：你的 skill 目录里有哪些文件，它就会在合适的时候去读取它们。
最简单的渐进式披露方式，就是把更细的内容拆分到其他 markdown 文件中供 Claude 使用。比如，你可以把详细的函数签名和调用示例拆到 references/api.md 里。
再比如，如果你的最终输出是一个 markdown 文件，那么你可以在 assets/ 目录里放一个模板文件，供 Claude 复制和使用。
你还可以建立 references、scripts、examples 等子目录；这些结构都会帮助 Claude 更高效地工作。
4-避免把 Claude 限死在一条轨道上
Claude 通常会尽量遵循你的指令。也正因为 Skills 具有很强的可复用性，所以你要特别警惕：不要把指令写得过于具体。你需要给 Claude 足够的信息，但同时也要给它留出根据具体情境灵活调整的空间。
5-把前置设置想清楚
有些 skill 需要先结合用户提供的上下文完成初始化设置。举例来说，如果你做的是一个把 standup 发到 Slack 的 skill，那么你可能会希望 Claude 先询问：应该发到哪个 Slack 频道。
一种很好的做法，是像前面的例子那样，把这些 setup 信息存放在 skill 目录里的 config.json 文件中。这样一来，如果配置尚未完成，agent 就可以主动向用户询问信息。
如果你希望 agent 以结构化、多选题的方式向用户提问，那么可以 instruct Claude 使用 AskUserQuestion 工具。
6-Description 字段是写给模型看的
当 Claude Code 启动一个 session 时，它会构建一份清单，列出所有可用的 skill 及其 description。Claude 正是通过扫描这份清单来判断：“这个请求有没有对应的 skill 可以调用？”
这意味着，description 字段并不是摘要，而是用来描述：这个 skill 应该在什么情况下被触发。
7-记忆与数据存储
有些 skill 可以通过在自身内部存储数据，形成某种 memory（记忆机制）。你既可以把数据存成最简单的“仅追加”文本日志文件或 JSON 文件，也可以复杂到使用 SQLite 数据库。
例如，一个 standup-post skill 可以维护一个 standups.log，记录它写过的每一条 standup。这样，当你下一次运行它时，Claude 就能读取自己的历史记录，并判断出相较于昨天究竟发生了哪些变化。
不过，存放在 skill 目录中的数据，在你升级 skill 时有可能会被删除。因此，这类数据应当存放到一个稳定目录中。按照原文所述，目前可以使用 ${CLAUDE_PLUGIN_DATA} 作为每个 plugin 独立的稳定数据目录。
8-存放脚本，并让 Claude 生成代码
你能交给 Claude 的最强大工具之一，就是代码本身。向 Claude 提供脚本与库，可以让它把有限的轮次花在“组合能力”上——也就是决定下一步该做什么——而不是把时间浪费在反复重建样板代码（boilerplate）上。
例如，在一个数据科学 skill 中，你可以准备一套从事件源抓取数据的函数库。这样一来，当 Claude 需要完成更复杂的分析时，你就可以为它提供一组辅助函数。
随后，Claude 就可以按需动态生成脚本，把这些能力拼接起来，去完成更高级的分析任务，例如回答“周二到底发生了什么？”这样的问题。
9-按需启用的 Hooks
Skills 可以包含一种 hooks：它们只会在该 skill 被调用时才激活，并且会持续到整个 session 结束。对于那些你并不希望一直开启、但在某些场景下又极其有用的强约束 hooks，这是一种非常合适的用法。
例如：
• /careful—— 通过 Bash 上的PreToolUse匹配器，阻止执行rm -rf、DROP TABLE、force-push、kubectl delete等操作。只有当你明确知道自己正在操作生产环境（prod）时，才会想启用它；如果始终开着，很快就会让人抓狂。• /freeze—— 阻止任何不在指定目录内的 Edit / Write 操作。原文在这里被截断，只能确认它接着提到：这在调试（debugging）时很有用，例如“我只是想加日志，但却总是不小心顺手把无关问题也‘修了’”。上传文件到这里已不完整，因此我没有继续补写。
分发 Skills
Skills 最大的价值之一，就是你可以把它们分享给团队中的其他人。
通常有两种方式可以把 skills 分享出去：
• 直接把 skills 提交进你的代码仓库（repo），放在 ./.claude/skills目录下• 做成一个 插件，并建立 Claude Code 的插件市场，让用户能够上传和安装这些插件。
对于仓库数量不多、规模相对较小的团队来说，直接把 skills 放进 repo 往往已经很好用。但每一个被直接提交进仓库的 skill，都会给模型上下文增加一点负担。随着团队规模扩大，建立一个内部的插件市场会更合适：它既能帮助你更好地分发 skills，也能让团队成员自行决定安装哪些技能。
管理 Marketplace
你该如何决定：哪些 skills 应该进入 marketplace？大家又应该如何提交它们？
我们的做法，并不是设立一个集中式团队来统一裁决；相反，我们更倾向于让真正有价值的 skill 自然“长出来”。如果你有一个 skill，希望别人试用，可以先把它上传到 GitHub 里的一个 sandbox 文件夹，再在 Slack 或其他讨论渠道中把链接发给大家。
当一个 Skill 获得了足够的关注（由 Skill 的作者自己判断），就可以提交 PR 把它移到插件市场中。
不过需要提醒的是：做出质量不高、或者内容重复的 skills，其实是很容易的。因此，在正式发布之前，确保你有某种 curation（筛选与治理） 机制，会非常重要。
组合使用 Skills
有时你会希望不同的 skills 之间能够互相依赖。比如，你可能有一个文件上传 skill 负责上传文件，又有一个 CSV 生成 skill 负责先生成 CSV 再上传。
这种 dependency management（依赖管理），目前在 marketplace 或 skills 体系里还没有原生支持；不过，你可以直接通过名字去引用其他 skills。只要这些 skills 已经安装，模型就会在需要时调用它们。
衡量 Skills 的效果
为了了解一个 skill 的实际表现，我们使用了一个 PreToolUse hook，在公司内部记录各个 skill 的使用情况。
这样一来，我们就能识别出：哪些 skills 很受欢迎，哪些 skills 的触发频率又低于预期。
结语
对于 agents 来说，Skills 是一种极其强大而灵活的工具；但这仍然是一个很早期的阶段，我们所有人都还在摸索：究竟怎样使用它们才算最好。
与其把这篇文章看作一份“定论式指南”，不如把它理解为一包已经被验证过、值得借鉴的实用经验。理解 skills 的最好方式，就是尽快开始动手，持续实验，然后看看什么方法对你真正有效。
我们内部的大多数 skill，最初都只是几行说明外加一条 gotcha（易踩坑事项）。之所以后来越来越成熟，是因为随着 Claude 不断撞上新的边界情况，人们持续把新的经验补充进去。
希望这些内容对你有帮助。
