Lessons from Building Claude Code: How We Use Skills

原文链接：https://x.com/trq212/status/2033949937936085378

概述

Anthropic 在 Claude Code 中使用 Skills 的经验总结。Skills 已成为最常用的扩展点之一，具有灵活、易于制作和简单分发的特点。文章通过实际经验整理出了技能的类型、制作技巧和分发建议。

---

Skills 是什么？

Skills 不仅仅是 markdown 文件，而是文件夹，可以包含脚本、资源、数据等，供 agent 发现、探索和操作。

Claude Code 中的 Skills 提供了丰富的配置选项，包括注册动态钩子（hooks）。

---

9 种技能类型

类型	用途	示例
1. Library & API Reference	解释库、CLI 或 SDK 的正确用法	billing-lib、frontend-design
2. Product Verification	描述如何测试或验证代码是否正常工作	signup-flow-driver、checkout-verifier
3. Data Fetching & Analysis	连接数据和监控栈	funnel-query、grafana
4. Business Process & Team Automation	将重复性工作流自动化为一条命令	standup-post、weekly-recap
5. Code Scaffolding & Templates	生成框架样板代码	new-migration、create-app
6. Code Quality & Review	强制执行代码质量标准	adversarial-review、code-style
7. CI/CD & Deployment	帮助部署代码	babysit-pr、deploy-<service>
8. Runbooks	接收症状 → 多工具调查 → 生成结构化报告	<service>-debugging、oncall-runner
9. Infrastructure Operations	执行常规维护和操作流程	<resource>-orphans、cost-investigation

最佳实践：每个技能应干净地归入一种类型，跨越多种类型的技能会造成混乱。

---

制作技巧

1. 不要陈述显而易见的事

专注于那些能将 Claude 从常规思维中拉出来的信息。例如 frontend-design 技能由 Anthropic 工程师迭代改进，重点是避免 Inter 字体和紫色渐梯度经典设计模式。

2. 建立「Gotchas」部分

每个技能中信号最高的內容就是 Gotchas 部分。这些部分应该从 Claude 使用时遇到的常见失败点中总结出来，并随着使用不断更新。

3. 使用文件系统实现渐进式披露

• 技能是文件夹，不只是 markdown 文件
• 简单的渐进式披露：指向其他 markdown 文件（如 references/api.md）
• 可以包含 assets/ 文件夹存放模板供 Claude 复制使用
• 可以有 references/、scripts/、examples/ 等文件夹

4. 避免让 Claude 陷入条条框框

给 Claude 所需的信息，但要给它适应情况的灵活性。

5. 考虑 Setup 流程

如果技能需要用户上下文（如 Slack channel），可以使用 config.json 存储设置信息。如果未配置，agent 可以询问用户。

6. Description 字段是给模型用的

Claude Code 启动时会根据 description 决定是否触发某个技能，所以 description 字段描述的是何时触发而非内容摘要。

7. 使用 Memory 存储数据

• 可以存储在 append-only 日志文件、JSON 文件，甚至 SQLite 数据库
• ${CLAUDE_PLUGIN_DATA} 提供每个插件的稳定存储文件夹
• 例如 standup-post 技能保存 standups.log，下次运行时可以对比昨天的变化

8. 存储脚本和生成代码

给 Claude 脚本和库让它专注于组合和决策，而不是重构样板代码。

9. 按需钩子（On Demand Hooks）

技能可以包含只在技能被调用时才激活的钩子，适用于那些不需要一直开启但偶尔非常有用 的配置。

示例：

• /careful — 阻止 rm -rf、DROP TABLE、force-push 等危险操作
• /freeze — 阻止不在特定目录中的 Edit/Write 操作

---

分发技能

两种方式

1. 检查式（Repo 内）：将技能检查到 .claude/skills 目录

   • 适合小型团队和较少仓库
   • 注意：每个检查的技能都会增加模型上下文

2. 插件市场：创建 Claude Code Plugin marketplace

   • 适合规模化团队
   • 让团队成员自行决定安装哪些技能

管理市场

• 没有集中式团队决定哪些技能上架
• 有用技能自然浮现：先放到 GitHub sandbox 文件夹，在 Slack 或论坛分享
• 技能获得关注后（由技能所有者判断），可以提交 PR 移入市场
• 警告：需要一定的审查机制，防止低质量或重复的技能

技能组合

技能可以相互依赖。例如文件上传技能 + CSV 生成技能可以组合使用。虽然市场目前不支持依赖管理，但可以直接按名称引用其他技能，模型会在安装时调用它们。

衡量技能效果

使用 PreToolUse 钩子记录技能使用情况，可以发现哪些技能受欢迎或触发不足。

---

结论

技能是 Agents 强大而灵活的工具，但目前仍处于早期阶段。

核心建议：

• 不要把这当作权威指南，而是一袋有用的技巧
• 最好的学习方式是动手开始、实验、观察什么适合你
• 大多数技能最初只有几行和一个 gotcha，随着 Claude 遇到新的边缘情况而不断改进

---

总结来源：Anthropic 官方分享