最近读到 Anthropic 工程师 Thariq 分享的一篇文章，讲他们在 Claude Code 内部大规模使用 Skills 的经验，近万字干货满满，结合我自己用 OpenClaw 的体会，整理成这篇。

Skills 是什么

很多人以为 Skills 就是" Markdown 文件"，实际上 Skills 是文件夹，可以包含脚本、资源、数据等。Agent 能发现、探索、操作这些文件，这才是 Skills 最有意思的地方。

Skills 已经成为 Claude Code 最常用的扩展点之一——灵活、易做、易分发。但正因为太灵活，反而很难判断什么场景最适合用它。

Skills 的 9 种类型

Thariq 团队把所有 Skills 做了梳理，发现可以归为 9 类：

类型 说明 例子
Library & API Reference 解释库/SDK 正确用法 billing-lib, frontend-design
Product Verification 测试验证代码是否正常工作 signup-flow-driver, checkout-verifier
Data Fetching & Analysis 连接数据和监控栈 funnel-query, grafana
Business Process Automation 自动化重复工作流 standup-post, weekly-recap
Code Scaffolding & Templates 生成框架模板 new-migration, create-app
Code Quality & Review 代码质量审查 adversarial-review, code-style
CI/CD & Deployment 部署相关 babysit-pr, deploy-service
Runbooks 故障排查手册 service-debugging, oncall-runner
Infrastructure Operations 日常运维操作 resource-orphans, cost-investigation

好的 Skills 边界清晰，只属于某一类；模糊的 Skills 往往跨越了多类。

写好 Skills 的 9 条 Tips

Tip 1: 不要写显而易见的东西

Skills 不是教 Claude 怎么写代码，而是记录** Claude 容易出错的地方**。写之前先问自己：Claude 在这件事上最容易踩什么坑？

Tip 2: 建立 Gotchas 章节

这是最有价值的部分。从失败案例中积累注意事项，价值远高于操作步骤。

Tip 3: 利用文件系统 + 渐进式披露

用文件夹组织参考代码、示例、脚本。SKILL.md 给概览，文件夹里放详细内容。Agent 可以自己探索，不需要把所有东西都塞进一个文件。

Tip 4: 避免把 Claude 绑死

给目标和约束，别给死板的步骤。Claude 需要知道要做什么，而不是一步步怎么执行。

Tip 5: 考虑 Setup

用 config.json 存储配置信息（API 地址、Token、仪表盘 ID 等），而不是写在 SKILL.md 里。这样配置可以独立更新。

Tip 6: Description 是给 Model 看的

description 决定何时触发这个 Skill。这是模型决定是否调用这个 Skill 的依据，要写得具体。

Tip 7: 记忆与数据存储

用 ${CLAUDE_PLUGIN_DATA} 存储持久数据，比如上一个运行结果、工作流历史。这能帮助 Agent 保持一致性。

Tip 8: 存脚本而非只写指令

给 Agent 可组合的脚本，比让它自己写更好。参考代码存在文件夹里，Agent 可以调用。

Tip 9: 按需 Hooks

Skills 可以包含只在调用时激活的 Hook，持续整个 session。

比如 /careful — 通过 PreToolUse 阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等危险操作。

比如 /freeze — 阻止除特定目录外的任何 Edit/Write。

分发策略

两种方式：

  1. 纳入代码仓库 — 放在 .claude/skills 下，适合小团队
  2. 做内部插件市场 — 用户上传安装，适合大规模团队

市场不需要中心化审核。先在 Slack 等渠道自然推广，有一定流行度后再移入市场。

我的感受

Skills 本质上是把经验和规则结构化存储，让 Agent 在需要时能调用。

这和我们写技术文档的逻辑很像——不是为了记录流水账，而是为了捕捉容易犯错的地方和最佳实践。

最好的 Skills 往往很简单，几行说明加一个 Gotchas 清单，然后随着 Agent 遇到新问题不断补充。

原文：Lessons from Building Claude Code: How We Use Skills — Thariq (@trq212)