Anthropic 官方 Skills 最佳实践：从"Markdown 文件"到"Agent 工具箱"

> 来源: https://x.com/trq212/status/2033949937936085378

> 作者: Thariq（@trq212）— Anthropic Claude Code 团队，前 YC W20，MIT Media Lab

> 发布时间: 2026-03-18

> 数据: 142 万查看 | 5,819 喜欢 | 1.6 万书签 | 819 转帖

> 研究时间: 2026-03-17

🎯 一句话版本

Anthropic 内部用了数百个 Skills，他们发现最好的 Skill 不是"一个 Markdown 文件"，而是"一个文件夹"——里面包含脚本、参考代码、配置模板、数据存储。Skill 的本质是给 Agent 一个可以探索和操作的"工具箱"，而不只是一段指令。

🏗️ 9 类 Skill 分类

Anthropic 把内部数百个 Skills 归纳为 9 类。这个分类本身就是最大的价值——帮你检查"我们缺了哪类"。

1. 📚 Library & API Reference（库/API 参考）

解释：教 Agent 如何正确使用某个库、CLI 或 SDK。通常包含代码片段文件夹和"踩坑列表"。

examples/
├── billing-lib — 内部计费库的边界情况和陷阱
├── internal-platform-cli — 内部 CLI 每个子命令的示例
└── frontend-design — 让 Claude 更懂你的设计系统

2. ✅ Product Verification（产品验证）

解释：描述如何测试/验证代码是否正常工作。通常配合 Playwright、tmux 等外部工具。

> Anthropic 的建议：值得让一个工程师花一整周只做验证类 Skill。

技巧：

• 让 Claude 录制测试过程的视频
• 在每个步骤强制做程序化断言
• Skill 里包含各种测试脚本

examples/
├── signup-flow-driver — headless 浏览器跑注册→邮件验证→onboarding 全流程
├── checkout-verifier — Stripe 测试卡跑结账，验证发票状态
└── tmux-cli-driver — 交互式 CLI 测试（需要 TTY）

3. 📊 Data Fetching & Analysis（数据获取与分析）

examples/
├── funnel-query — "哪些事件串联能看到 注册→激活→付费"
├── cohort-compare — 对比两个用户群的留存或转化
└── grafana — 数据源 UID、集群名称、问题→仪表盘对照表

4. 🔄 Business Process & Team Automation（业务流程自动化）

examples/
├── standup-post — 聚合票务系统+GitHub活动+Slack → 格式化站会报告
├── create-ticket — 强制 schema（有效枚举值、必填字段）+ 创建后工作流
└── weekly-recap — 合并的 PR + 关闭的 ticket + 部署 → 周报

5. 🏗️ Code Scaffolding & Templates（代码脚手架）

examples/
├── new-<framework>-workflow — 用你的注解生成新服务/handler
├── new-migration — 迁移文件模板 + 常见陷阱
└── create-app — 预装 auth/logging/deploy 配置的新应用

6. 🔍 Code Quality & Review（代码质量审查）

examples/
├── adversarial-review — 生成一个"全新视角"的子 Agent 来批评，修复，迭代到只剩 nitpick
├── code-style — 强制代码风格（尤其是 Claude 默认做不好的）
└── testing-practices — 测试方法论和测试范围指导

7. 🚀 CI/CD & Deployment

examples/
├── babysit-pr — 监控 PR → 重试 flaky CI → 解决合并冲突 → 自动合并
├── deploy-<service> — build→冒烟→渐进流量→错误率对比→自动回滚
└── cherry-pick-prod — 隔离 worktree → cherry-pick → 冲突解决 → PR

8. 📋 Runbooks（运维手册）

examples/
├── <service>-debugging — 症状→工具→查询模式 映射表
├── oncall-runner — 获取告警 → 检查常见原因 → 格式化报告
└── log-correlator — 给一个 request ID，从所有系统拉相关日志

9. 🔧 Infrastructure Operations（基础设施运维）

examples/
├── <resource>-orphans — 找孤儿 pod/volume → 发 Slack → 等待期 → 确认 → 清理
├── dependency-management — 你组织的依赖审批流程
└── cost-investigation — "为什么存储/出口带宽账单暴涨"的排查模式

💡 10 条 Skill 编写秘诀

1. 别说废话（Don't State the Obvious）

Claude 已经知道很多编码知识。Skill 应该把 Claude 推出它的默认思维，而不是重复它已经知道的。

> 好例子：Anthropic 的 frontend-design Skill 是工程师和客户反复迭代出来的——教 Claude 避免 Inter 字体和紫色渐变这种"AI 味设计"。

2. 建立"踩坑清单"（Build a Gotchas Section）

任何 Skill 中信噪比最高的部分就是 Gotchas。 从 Claude 使用 Skill 时遇到的常见失败点积累，持续更新。

3. 用文件系统做渐进式暴露（Progressive Disclosure）

Skill 是文件夹，不是文件。把整个文件系统当作上下文工程的工具。

my-skill/
├── SKILL.md            ← 主入口（告诉 Claude 有哪些文件可读）
├── references/
│   └── api.md          ← 详细函数签名和用法
├── assets/
│   └── template.md     ← 输出模板
├── scripts/
│   └── fetch_data.py   ← 可执行脚本
└── examples/
    └── good_output.md  ← 参考示例

告诉 Claude 有这些文件，它会在合适的时候自己去读。

4. 别把 Claude 逼死（Avoid Railroading）

给信息，但留灵活度。Skill 会被反复使用，太死板的指令会限制 Claude 适应不同场景。

5. 想清楚 Setup 流程

需要用户配置的 Skill（比如 Slack 频道名），用 config.json 模式：

如果 config.json 不存在 → 问用户要配置信息 → 保存 → 下次自动读取

6. Description 是给模型看的触发条件

Claude Code 启动时扫描所有 Skill 的 description。Description 不是"摘要"，是"什么时候该触发这个 Skill"的判断依据。

7. 用文件做记忆（Memory & Storing Data）

Skill 可以在自己目录下存数据——追加日志、JSON、甚至 SQLite。

standup-post/
├── SKILL.md
└── standups.log   ← 每次生成的站会记录，下次运行时 Claude 读历史

> ⚠️ Skill 目录可能在升级时被删除。用 $CLAUDE_PLUGIN_DATA 作为稳定存储路径。

8. 存脚本，让 Claude 组合（Store Scripts & Generate Code）

给 Claude 预写好的库函数，Claude 专注于组合而不是重写样板代码。

# scripts/fetch_events.py — 预写的数据获取函数
def get_events(start, end): ...
def get_user_sessions(user_id): ...

Claude 可以临时生成脚本来组合这些函数完成复杂分析。

9. On-Demand Hooks（按需钩子）

Skill 可以注册只在被调用时才激活的钩子：

• /careful — 阻止 rm -rf、DROP TABLE、force-push（只在操作 prod 时开）
• /freeze — 阻止编辑指定目录之外的文件（调试时用）

10. 度量 Skill 使用情况

用 PreToolUse hook 记录每个 Skill 被调用的频率，找到热门 Skill 和触发不足的 Skill。

📦 分发方式

Anthropic 的内部实践：先放 sandbox 文件夹让人试用 → 有 traction 后 PR 进 marketplace。

> ⚠️ "创建差或重复的 Skill 非常容易，发布前一定要有筛选机制。"

🤔 深度分析

这篇文章的真正价值

不是具体的 9 类分类（虽然很有用），而是思维模型的转变：

以前：Skill = 一段 prompt

现在：Skill = 一个可探索的工具箱（文件夹 + 脚本 + 数据 + 钩子 + 配置）

这和我们之前讨论的 Context Hub（Andrew Ng）的"文档即 Skill"理念一脉相承——给 Agent 结构化的上下文比给它一段长指令更有效。

Anthropic 的 Skill 成熟度模型

从文章可以推断出 Anthropic 内部的 Skill 生命周期：

几行 Markdown + 一个 gotcha
    ↓
不断添加更多 gotchas
    ↓
加入参考代码文件夹
    ↓
加入脚本和自动化
    ↓
加入 config.json 和数据存储
    ↓
提交到 marketplace
    ↓
用 PreToolUse hook 度量效果

与 OpenClaw Skills 的对照

我们缺的：

1. On-Demand Hooks — OpenClaw 没有 PreToolUse/PostToolUse 钩子机制

2. 使用度量 — 不知道哪些 Skill 被调用了多少次

3. 稳定数据目录 — 没有 $CLAUDE_PLUGIN_DATA 等价物

💡 与我们的关联

1. 检查我们缺哪类 Skill

用 9 类分类检查我们的 OpenClaw Skills：

缺口：Product Verification、Code Quality、Runbooks。

2. Gotchas 清单模式值得采纳

我们的 AGENTS.md 可以加一个"常见踩坑"section——每次遇到问题就追加。这是 Anthropic 说的"Skill 中信噪比最高的部分"。

3. 渐进式暴露已经在用

我们的 docs/deep-research/raw/ + docs/deep-research/ 结构其实就是渐进式暴露——原始数据和报告分层。可以更系统化。

4. "别说废话"原则

我们的 Skill 应该专注于 Claude 默认做不好的事情，而不是重复它已经知道的。

📊 评分

报告由深度研究助手自动生成 | 2026-03-17

来源: https://x.com/trq212/status/2033949937936085378