Lessons from Building Claude Code: How We Use Skills

这篇文章的核心价值：把“Skill 只是 markdown”这个误解打掉，重新把 Skill 看成一种可组合的 agent extension point：它可以带脚本、数据、模板、hooks、记忆与分发机制。

文章在回答什么

• 什么样的 skill 值得做
• 好 skill 的秘密是什么
• 什么时候该共享给别人
• 怎么避免做出坏 skill

一个关键纠偏

Skill 不只是 markdown 文件。

更准确地说，它是一个文件夹：

• 可以带脚本
• 可以带 assets
• 可以带数据
• 可以带 hooks
• 可以让 agent 逐步探索和组合

作者的总判断

最好的 skills 通常：

• 类型清晰
• 目标明确
• 能补 Claude 的短板
• 能复用
• 能随着失败案例持续迭代

这篇文章的底层视角

Skill 本质上是一个 context + tooling + workflow 的封装单元。

它不是把知识堆给模型，而是把：

• 正确的上下文入口
• 正确的脚本 / 模板 / hooks
• 正确的触发时机 一起交给模型。

1. Library & API Reference

教 Claude 正确使用某个库、CLI、SDK。

典型内容：

• 示例代码
• 函数签名
• footguns / edge cases
• 组织内部约定

2. Product Verification

告诉 Claude 怎么验证产出真的能工作。

常与 Playwright、tmux 搭配，重点是：

• 可执行验证脚本
• 程序化断言
• 录屏 / 留证据

作者明确说：这是非常值得重投入的一类。

3. Data Fetching & Analysis

连接数据仓、监控栈、仪表盘。

本质是把：

• 凭据
• 数据源标识
• 常用查询模式
• 指标解释 封装成可复用工作流

4. Business Process & Team Automation

把重复团队流程压成一个命令。

例如：

• standup
• 建 ticket
• weekly recap

这类 skill 通常不复杂，但非常省时间。

5. Code Scaffolding & Templates

生成你组织里的标准脚手架。

适合处理：

• 模板化代码
• 自然语言需求
• 单纯脚本难覆盖的规范

6. Code Quality & Review

把代码质量和审查策略写进 skill。

例如：

• code style
• testing practices
• adversarial review

可和 hooks / GitHub Action 联动。

7. CI/CD & Deployment

帮助拉代码、发代码、部署代码。

典型是多步流程： build -> test -> smoke -> rollout -> compare -> rollback

8. Runbooks

给一个症状，按固定调查路径跑多工具诊断，再产出结构化报告。

适合：

• oncall
• alert triage
• request id 追踪
• 常见故障排查

9. Infrastructure Operations

把高风险运维流程加上 guardrails。

适合：

• 清理孤儿资源
• 依赖治理
• 成本调查
• 带确认与 soak period 的清理

9 类 Skill 的共同点

它们本质上都不是“写给人看的说明书”，而是“写给模型执行的工作单元”。

区别只在于：

• 补知识
• 补验证
• 补数据入口
• 补流程编排
• 补安全边界

作者的隐含建议

好的 skill 最好清晰落在某一类里。

一旦一个 skill 横跨太多类型，往往会：

• 触发条件模糊
• 内容臃肿
• 维护困难
• 复用性下降

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

Claude 本来就懂很多编码常识。

Skill 应该优先写那些会把模型拉出默认思路的信息，而不是重复基础知识。

2. Build a Gotchas Section

最高信号密度的内容往往是 gotchas。

也就是：

• Claude 常犯什么错
• 这类工作里最容易踩什么坑
• 哪些边界条件必须提前说

3. 把文件系统当作 context engineering

Skill 是文件夹，不是单文件。

可以用：

• references/
• examples/
• assets/
• scripts/ 做 progressive disclosure

4. Avoid Railroading Claude

别把 skill 写成死流程。

原则是：

• 给足信息
• 不要过度规定每一步
• 保留模型根据上下文自适应的空间

5. 认真设计 Setup

有些 skill 需要用户上下文，例如频道、环境、目标系统。

推荐把 setup 信息放在 skill 目录的 config.json，未配置时再问用户。

6. Description 字段是写给模型的

它不是“摘要”，而是触发描述。

Claude 会扫全部 skill 的 description 来判断： “这个请求有没有对应的 skill？”

7. Skill 也可以有记忆

可以存：

• append-only log
• JSON
• SQLite

但升级 skill 时目录内数据可能被删，所以稳定数据建议放 ${CLAUDE_PLUGIN_DATA}。

8. 把脚本和代码交给 Claude

给 helper functions、脚本库、模板后，Claude 的 token 就能花在“组合与决策”上，而不是重复造 boilerplate。

1. 两种分发方式

• 跟 repo 一起放进 ./.claude/skills
• 做成 plugin，进入 marketplace

前者简单，后者更适合规模化分发

2. Repo 分发的代价

每多一个 checked-in skill，都会给模型多一点上下文负担。

小团队问题不大，规模大了就需要更精细的安装与裁剪。

3. Marketplace 的价值

让技能变成按需安装，而不是全量塞给每个仓库。

这样团队可以：

• 更好分发
• 更好治理
• 更少上下文污染

4. 不要搞中心化审批

Anthropic 的做法是先有机扩散，再在 skill 有 traction 后进入 marketplace。

5. 需要策展

坏 skill 和重复 skill 很容易出现。

所以在正式发布前，必须有某种 curation 机制。

6. Skills 可以互相组合

虽然市场和依赖管理还不完善，但可以直接在 skill 里引用其他 skill 名称，让模型在安装后自行调用。

7. 要测量 skill

Anthropic 用 PreToolUse hook 记录使用情况，以识别：

• 哪些 skill 热门
• 哪些 undertrigger
• 哪些值得继续投资

A. 先别从“我想写个 skill”开始

更好的起点是：

• Claude 在什么地方反复犯错
• 哪个流程反复重复
• 哪个验证步骤总被忽略
• 哪种查询总靠老人记忆

B. 每个 Skill 的最小骨架

1. 清晰类型
2. 真正有用的 description
3. gotchas
4. references / examples / scripts
5. 必要的 setup config
6. 可选的记忆与 hooks

C. 优先级建议

如果资源有限，最值得先做的通常是：

1. Product Verification
2. Code Quality & Review
3. Runbooks
4. Data Fetching & Analysis

因为这些直接影响结果正确性与排障效率。

D. 团队 rollout 路线

• 先在 repo 内试验
• 用 usage / trigger 数据看 traction
• 逐步清理重复 skill
• 成熟后再进 marketplace

这是比一开始“大一统平台化”更稳的路径。

E. 这篇文章真正想让你记住的 3 件事

1. Skill 是文件夹，不是 markdown。
2. Gotchas、scripts、progressive disclosure 往往比长篇说明更有用。
3. Skill 体系也需要分发、策展和度量。

9. On Demand Hooks

Skill 可以带只在调用时激活、并持续到会话结束的 hooks。

适合高 opinionated、但不该常开的约束：

• 阻止危险命令
• 限定编辑目录
• 进入 prod / debug 模式时增加额外护栏