今年3月，Claude Code团队成员Thariq在X平台发布了一篇长文，详细分享了Anthropic内部运用Skill的实践经验。文章指出，Anthropic内部已有数百个Skill处于活跃使用状态。
这篇文章并未局限于SKILL.md的写法。除了介绍九类内部用法外，还涵盖了Gotchas、渐进式披露、脚本、动态Hook、团队分发以及使用统计等内容。对于那些正将Claude Code从个人工具推向团队工作流的人来说，这些细节比再复制一份模板更具参考价值。
Skill已成为Claude Code应用最广泛的扩展点之一。其灵活性、易制作性和易分发性，使其在众多扩展中脱颖而出。
然而，灵活性也带来了选择上的困惑：哪些类型的Skill值得投入？编写一个优秀Skill的关键秘诀是什么？何时应该将其分享给他人？Anthropic内部广泛使用Claude Code Skills，目前已有数百个处于活跃状态。以下经验来自他们利用Skills加速开发的实际过程。
Skill是什么？
如果你刚接触Skills，建议先查阅官方文档，或观看Skilljar上的最新Agent Skills课程。这里假设你对Skills已有一定了解。
一个常见的误解是：Skill“就是一个Markdown文件”。这种说法忽略了Skill最关键的能力——它实际上是一个文件夹，可以包含脚本、资产、数据等内容，Agent能够发现、查看并操作这些文件。在Claude Code中，Skill还提供了多种配置选项，包括注册动态Hook。一些富有创造力的Skill，正是将配置能力与文件夹结构巧妙结合。
Skill的类型
从内部盘点来看，这些Skill大多集中在几个反复出现的类别中。好用的Skill通常能清晰归入一类；而令人困惑的Skill往往横跨多个类别。以下清单并非最终或完整，但它能帮助你检查自己的组织是否缺少某一类能力。
1. Library & API Reference，库与API参考。这类Skill说明如何正确使用某个库、CLI或SDK，既适用于内部库，也适用于Claude Code偶尔难以正确使用的通用库。它们通常附带一个参考代码片段目录，以及一份Claude编写脚本时需要避开的Gotchas清单。示例包括：billing-lib，记录内部计费库的边缘情况与易踩陷阱；internal-platform-cli，列出内部CLI包装器的每个子命令及其适用场景；frontend-design，帮助Claude更好地使用团队设计系统。
2. Product Verification，产品验证。这类Skill说明如何测试或验证代码是否真正可用，通常会配合Playwright、tmux等外部工具完成检查。验证Skill对保证Claude输出正确性非常有帮助，有时值得让一名工程师专门花一周时间，把团队的验证Skill做扎实。可以让Claude录制输出视频，让人准确看到它测试了什么；也可以在每一步对状态执行程序化断言。这些能力通常由Skill目录中的多种脚本实现。示例包括：signup-flow-driver，在无头浏览器中完成注册、邮件验证和新手引导，并用Hook断言每一步状态；checkout-verifier，使用Stripe测试卡操作结账界面，再确认发片确实进入正确状态；tmux-cli-driver，测试必须运行在真实TTY中的交互式CLI。
3. Data Fetching & Analysis，数据获取与分析。这类Skill连接团队的数据与监控栈。它可以包含带凭据的数据获取库、特定仪表盘ID，以及常见工作流和取数方式的说明。示例包括：funnel-query，回答“要看注册、激活到付费的漏斗，应该连接哪些事件”，并指出真正保存规范user_id的表；cohort-compare，比较两个群组的留存或转化，标出有统计显著性的差异，并链接到分群定义；grafana，记录数据源UID、集群名称，以及从问题到仪表盘的查询映射表。
4. Business Process & Team Automation，业务流程与团队自动化。这类Skill将重复工作压缩成一条命令。说明本身通常不复杂，但可能依赖其他Skill或MCP。将历次结果保存在日志文件中，有助于模型保持一致性，并回顾此前每一次工作流执行。示例包括：standup-post，汇总工单系统、GitHub活动和上一份Slack站会，只输出新增变化并整理成站会格式；create-
5. Code Scaffolding & Templates，代码脚手架与模板。这类Skill为代码库中的特定功能生成框架样板，也可以与可组合脚本一起使用。当脚手架包含无法完全用代码表达的自然语言要求时，它尤其有用。示例包括：new-
6. Code Quality & Review，代码质量与审查。这类Skill用于落实组织内部的代码质量要求并辅助Review。为了获得更稳健的结果，可以加入确定性脚本或工具，也可以通过Hook或GitHub Action自动运行。示例包括：adversarial-review，启动一个用全新视角审查代码的Subagent，修复发现的问题并持续迭代，直到剩下的都只是细枝末节；code-style，执行代码风格要求，尤其关注Claude默认不擅长遵守的部分；testing-practices，说明测试该如何编写、应该测试什么。
7. CI/CD & Deployment，持续集成、交付与部署。这类Skill帮助你在代码库中拉取、推送和部署代码，也可能引用其他Skill来收集数据。示例包括：babysit-pr，持续监控一个PR，重试偶发失败的CI、解决合并冲突并开启自动合并；deploy-
8. Runbooks，运行手册。这类Skill从一个症状出发，例如Slack线程、告警或错误签名，引导Agent使用多个工具完成调查，最后生成结构化报告。示例包括：
9. Infrastructure Operations，基础设施运维。这类Skill处理日常维护和运维流程，其中一些操作具有破坏性，因此很适合加入护栏。它能帮助工程师在关键操作中遵循最佳实践。示例包括：
制作Skill的技巧
决定要制作哪一种Skill之后，接下来就是如何编写。下面是一些实践中发现的有效方法、技巧和经验。近期还发布了Skill Creator，让Claude Code中创建Skill的过程更加便捷。
不要陈述显而易见的内容。Claude Code已经很了解你的代码库，Claude对编程也有大量的知识和默认倾向。如果发布的Skill主要用于补充知识，请优先写那些能将Claude推出惯常思路的信息。frontend-design Skill就是一个很好的例子：Anthropic的一名工程师通过持续与客户迭代来改善Claude的设计品位，并让它避开Inter字体、紫色渐变这类常见套路。
建立Gotchas小节。一个Skill中信号最强的内容，通常就是Gotchas。这个小节应随着Claude使用该Skill时经常遇到的失败点逐步积累。理想情况下，随着使用时间增长，你会持续更新Skill，把新出现的坑补进去。
使用文件系统与渐进式披露
前面提过，Skill是一个文件夹，不能只看成一份Markdown。整个文件系统都可以视作上下文工程和渐进式披露的一部分。告诉Claude这个Skill里有哪些文件，它就会在合适的时候读取它们。
最简单的渐进式披露，是指向其他Markdown文件供Claude按需使用。例如，可以将详细函数签名和使用示例拆分到references/api.md。如果最终产物是一份Markdown，也可以在assets/中放入模板，让Claude复制使用。Skill目录还可以包含references、scripts、examples等文件夹，帮助Claude更有效地完成工作。
不要把Claude限死
Claude通常会尽量遵循你的指令。由于Skill会被重复使用，编写指令时要谨慎，避免规定得过于细致。给Claude完成任务所需的信息，同时保留根据现场情况调整的空间。
提前想清楚初始化配置。有些Skill需要先向用户获取上下文。例如，一个负责将站会内容发到Slack的Skill，可能需要先询问应该发到哪个频道。一种好做法，是像示例中那样把配置保存在Skill目录的config.json。如果配置尚未完成，Agent再向用户提问。需要让Agent提出结构化的多选问题时，可以明确要求Claude使用AskUserQuestion工具。
Description字段是写给模型看的。Claude Code启动会话时，会根据所有可用Skill的description建立一份列表。Claude就靠这份列表判断“这个请求有没有对应的Skill”。因此，description的主要任务是说明什么时候应该触发这个Skill，而非写一段供人阅读的项目摘要。
记忆与数据存储。有些Skill可以把数据保存在自身目录中，从而形成一种记忆。实现方式可以很简单，例如只追加不修改的文本日志或JSON文件；也可以复杂到使用SQLite数据库。例如，standup-post Skill可以用standups.log保存发过的每一条站会内容。下次运行时，Claude读取自己的历史记录，就能判断与昨天相比发生了什么变化。Skill升级时，保存在Skill目录中的数据可能会被删除，因此应该写入稳定目录。目前每个插件提供${CLAUDE_PLUGIN_DATA}，作为持久保存数据的位置。
保存脚本，让Claude生成代码
代码是你能提供给Claude的强力工具之一。给Claude准备脚本和函数库，它就可以把推理轮次用在组合能力、决定下一步上，而无需每次重新拼装样板代码。
例如，数据科学Skill可以提供一组从事件源取数的函数。Claude随后可以临时生成脚本，把这些辅助函数组合起来，完成更复杂的分析，并回答“周二发生了什么？”这样的问题。
按需启用Hook。Skill可以注册只在被调用时激活、并持续到当前会话结束的Hook。它适合那些不应该一直运行，但在某些场景非常有用的强约束。例如：/careful通过Bash的PreToolUse Matcher阻止rm -rf、DROP TABLE、强制推送和kubectl delete，只在确定要操作生产环境时启用，否则一直开着会让人抓狂；/freeze阻止对指定目录之外的任何Edit或Write，适合“我只想加日志，却总是不小心顺手改掉无关内容”的调试场景。
分发Skills
Skill的一大好处，是可以分享给团队中的其他人。分享主要有两种方式：把Skill提交到代码仓库的./.claude/skills目录；或者将其制作成插件，并建立一个Claude Code Plugin Marketplace，让用户上传和安装插件。
如果小团队只在少数几个仓库中工作，直接将Skill提交进仓库就很方便。但每个进入仓库的Skill都会占用一点模型上下文。团队规模扩大后，内部Plugin Marketplace可以集中分发Skill，同时让每个人自行决定安装哪些。
管理Marketplace。哪些Skill应该进入Marketplace？提交方式应如何设计？没有设立一个集中决策的团队，而是让真正有用的Skill自然浮现。如果你想让别人试用你的Skill，可以先将其上传到GitHub的Sandbox目录，再通过Slack或其他论坛邀请大家使用。Skill获得足够使用量之后，具体标准由Skill Owner判断，就可以提交PR，将其移入Marketplace。需要注意的是，制作出质量差或功能重复的Skill很容易，因此正式发布前必须有某种筛选机制。
组合Skills。有些Skill会依赖其他Skill。例如，一个文件上传Skill负责上传文件，另一个CSV生成Skill负责创建CSV并调用上传能力。Marketplace和Skill目前没有内建这种依赖管理，但你可以直接在说明中引用其他Skill的名称；只要它们已经安装，模型就会调用。
度量Skills。为了了解一个Skill表现如何，我们使用PreToolUse Hook记录公司内部的Skill使用情况。这样就能找出哪些Skill很受欢迎，以及哪些Skill的触发次数低于预期。
结语
Skill是非常强大、灵活的Agent工具，但这个领域仍处在早期，大家都还在探索如何将其用好。
与其把本文当成一份权威指南，不如将它看作一包已经在实践中奏效的经验。理解Skill的最佳方式，是先行动起来、不断实验，再观察什么对自己有效。大多数Skill起步时只有几行文字和一个Gotcha；后来Claude遇到新的边缘情况，使用者不断把经验补进去，它们才一点点变好。