Claude Code的Skills已经成了我用得最多的扩展点。灵活、易做、容易分发，但正是因为太灵活，很多人反而不知道什么值得做、怎么做最好。Anthropic内部已经跑了几百个技能，这篇是他们整理的经验教训。

---

## 技能不是markdown文件

一个常见误解是技能“就是markdown文件”。实际上，技能是一个文件夹，可以包含脚本、资产、数据等，agent可以发现、探索和操作这些内容。Claude Code还提供了丰富的配置选项，比如注册动态hook。

最有价值的技能往往充分利用了这些配置选项和文件夹结构。

---

## 9种技能类型

Anthropic把几百个技能拆了又拆，最后发现能归进这几个类别：


**1. Library & API Reference**

解释怎么正确使用某个库、CLI或SDK。包括内部库或常用库的参考代码片段，还有一堆Claude容易踩的坑。

例子：billing-lib（内部计费库的各种边界情况）、internal-platform-cli（内部CLI的每个子命令用法）、frontend-design（让Claude更懂你的设计系统）。

**2. Product Verification**

验证代码是否正常工作。通常搭配Playwright、tmux之类的外部工具使用。这类技能值得花时间打磨——有人甚至花一周专门优化验证技能。

建议让Claude录下测试过程的视频，这样你能直接看到它测了什么。也可以在每个步骤嵌入程序化的断言。

例子：signup-flow-driver（跑完注册流程并在每步断言状态）、checkout-verifier（用Stripe测试卡驱动结账UI，验证发票状态）、tmux-cli-driver（交互式CLI测试）。

**3. Data Fetching & Analysis**

连接数据和监控栈。包含带凭证的数据获取库、特定dashboard ID、常用工作流和取数方式。

例子：funnel-query（哪些事件关联 signup→activation→paid）、cohort-compare（比较两个Cohort的留存或转化，标记统计显著差异）、grafana（数据源UID、集群名、问题→dashboard查找表）。

**4. Business Process & Team Automation**

把重复工作流压缩成一个命令。逻辑通常不复杂，但可能依赖其他技能或MCP。把之前的结果存进日志文件可以帮助模型保持一致。

例子：standup-post（汇总ticket tracker、GitHub活动、Slack→格式化站会，只显示变化）、create-ticket（强制schema规范加上创建后的工作流）、weekly-recap（合并的PR+关闭的ticket+部署→格式化周报）。

**5. Code Scaffolding & Templates**

生成特定框架的脚手架。当脚手架有纯代码无法覆盖的自然语言需求时，这些技能特别有用。

例子：new-workflow（搭一个新的service/workflow/handler，带你的注解）、new-migration（迁移文件模板加常见坑）、create-app（带auth、logging、deploy config的新内部app）。

**6. Code Quality & Review**

强制代码质量、帮助review。可以包含确定性脚本或工具保证最大鲁棒性。建议作为hook或GitHub Action自动运行。

例子：adversarial-review（启动一个fresh-eyes的子agent来批评，循环修复直到问题降级成挑刺）、code-style（强制代码风格，尤其是Claude默认做不好的那些）、testing-practices（怎么写测试、测什么）。

**7. CI/CD & Deployment**

帮你拉代码、推代码、部署代码。可以引用其他技能来收集数据。

例子：babysit-pr（监控PR→重跑 flaky的CI→解决合并冲突→开启自动合并）、deploy（构建→冒烟测试→渐进式流量切换+错误率对比→自动回滚）、cherry-pick-prod（隔离worktree→cherry-pick→解决冲突→带模板的PR）。

**8. Runbooks**

接收一个症状（Slack thread、alert或错误签名），走一遍多工具调查流程，产出结构化报告。

例子：oncall-runner（抓取alert→检查常见问题→格式化报告）、log-correlator（给定request ID，从每个可能相关的系统拉取匹配的日志）。

**9. Infrastructure Operations**

日常运维和操作流程，有些涉及破坏性操作，需要guardrails保护。

例子：orphans（找孤儿pod/volumes→发到Slack→浸泡期→用户确认→级联清理）、dependency-management（你组织的依赖审批流程）、cost-investigation（为什么存储/ egress账单暴涨，带具体的bucket和查询模式）。

---

## 制作技巧


**1. 跳过显而易见的**

Claude Code对你的代码库已经了解很多，Claude本身也懂编程，包括很多默认偏好。如果你在发布一个主要关于知识的技能，聚焦那些能把Claude从正常思路里拉出来的信息。

比如frontend-design技能，是Anthropic一个工程师和客户迭代改进Claude设计品味的成果，成功避开了Inter字体+紫色渐变这种经典俗套。

**2. 做一个Gotchas章节**


任何技能里信号最强的内容就是Gotchas部分。这些应该来自Claude使用这个技能时遇到的常见失败点。最好随着时间更新技能，持续捕获这些gotchas。

图中展示了billing-lib技能从Day 1的简单用法说明，到Week 2开始加入proration的坑，再到Month 3的一大串gotchas的演进过程。

**3. 用好文件系统+渐进式披露**

技能是文件夹，不是单个markdown文件。整个文件系统都可以看成是一种上下文工程和渐进式披露。告诉Claude你的技能里有哪些文件，它会在合适的时候去读取。

最简单的形式是指向其他markdown文件。比如把详细的函数签名和用法示例拆到references/api.md。

另一个例子：如果你的最终输出是个markdown文件，可以在assets/里放一个模板文件供复制使用。

**4. 别把Claude架在轨道上**

Claude会尽力遵循你的指令，而技能复用性很高，所以指令千万别写得太死。给Claude它需要的信息，但留给它适应情况的空间。

**5. 考虑好初始设置**

有些技能需要从用户那里获取初始上下文。比如做一个发站会到Slack的技能，你可能想让Claude问清楚发到哪个频道。

一个好的做法是把这些设置信息存到skill目录里的config.json。如果没设置好，agent可以让用户提供信息。如果想让agent抛出结构化的多选问题，可以指示它用AskUserQuestion工具。

**6. 描述是给模型看的**

Claude Code启动一个session时，会列出所有可用技能及其描述。Claude扫描这个列表来决定“有没有处理这个请求的技能”。这意味着描述字段不是总结——而是触发这个技能的条件。

**7. 用${CLAUDE_PLUGIN_DATA}存数据**

有些技能可以通过在里面存数据来实现一种记忆形式。简单可以是一个只增不减的文本日志或JSON文件，复杂可以是个SQLite数据库。

比如standup-post技能可以维护一个standups.log，记录它写过的每一次站会。这样下次运行时，Claude读到自己之前的历史，就能说出昨天以来有什么变化。

注意：skill目录里的数据在升级技能时可能被删除，所以应该存到稳定目录。目前他们提供${CLAUDE_PLUGIN_DATA}作为每个plugin的稳定存储文件夹。

**8. 给代码，别让Claude重建**

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

比如在你的数据科学技能里，放一个从事件源取数的函数库。要让Claude能做复杂分析，可以给它一套辅助函数，它就能动态生成脚本来组合这些功能，回答"周二发生了什么？"这类问题。

**9. 按需Hook**

技能可以包含只在调用时激活、持续整个session的hook。用在你不想一直开着但偶尔极其有用的强烈观点式hook。

比如/**careful**——通过PreToolUse matcher拦截rm -rf、DROP TABLE、force-push、kubectl delete。只有在碰生产时才需要这个，一直开着能逼疯你。

/**freeze**——只允许编辑/写入特定目录里的东西。调试时很有用：“我想加日志但总是不小心'修复'不相关的东西”。

---

## 分发与管理

技能的一大好处是可以分享给团队。两种方式：

- **直接打进repo**（放在./.claude/skills）

- **做plugin**，通过Claude Code Plugin marketplace分发

小团队跨几个repo用第一种就行。但每个打进repo的技能都会给模型上下文加点负担。规模大了之后，内部plugin marketplace更合适，让团队自己决定装哪些。

**怎么管理 marketplace？**

他们没有集中团队来决定。而是让最有用的技能自然浮现。你想让人试用一个技能，可以发到GitHub的sandbox文件夹，然后在Slack或其他论坛提一下。等技能有了足够的 traction（这由技能所有者判断），可以提PR把它搬进marketplace。

值得提醒的是，很容易做出差或重复的技能，所以在发布前确保有某种审核机制。

**技能依赖**

你可能想让技能之间有依赖。比如一个文件上传技能+一个CSV生成技能能组合成“生成CSV并上传”。目前marketplace和技能本身对这种依赖管理还没有原生支持，但可以按名字引用其他技能，模型会在装了的情况下调用它们。

---

## 一些补充想法

推特上有人补充了一些有趣的视角：

有人提到给技能加个“上次使用”日期，然后每两周审计一次没用的技能，保持技能列表新鲜，防止膨胀和重叠。

还有人提到，从营销材料一周做了17个技能，输出很惊艳，但eval viewer显示方式不太合理——这也是个值得注意的点：技能的产出形式和展示方式同样重要。

---

## 最后

技能是非常强大、灵活的工具，但还在早期，大家都在摸索。这篇更像是他们验证过有用的技巧集合，而不是权威指南。

最好的理解方式还是动手开始，实验，看看什么适合你。他们的技能大多起源于几行文字+一个gotcha，因为人们持续补充Claude遇到的新边界情况而变得越来越好。