Claude Code 工程实践揭秘：Anthropic 内部 Skills 设计的九类框架与编写最佳实践

公众号名称：AI 启蒙小伙伴

作者名称：邵猛

发布时间：2026-06-05 07:50

Claude 官方博客

这篇博客是 Anthropic 工程团队内部实践的经验总结，主题围绕 Claude Code 中 “Skills” 的设计、分类与最佳实践。是一份工程组织如何将隐性知识显性化、结构化地注入 AI 工作流的方法论文档。

Lessons from building Claude Code: How we use skills

What we learned building and scaling hundreds of skills internally at Anthropic.

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Skills 的本质：从”提示词”到”组织知识库”

文章首先建立了一个关键认知：Skill 不是一个 prompt，它是一个文件夹。它代表一种将组织内的隐性经验（tribal knowledge）封装为可复用 AI 上下文的工程实践。

核心设计哲学：

单一职责：最好的 skill cleanly fit into one category（干净地落入一个类别）；试图覆盖多个领域的 skill 会让 agent 困惑
渐进式披露：通过文件系统结构实现上下文工程（context engineering），而非把所有信息塞进一个文件
持续迭代：skill 是活的文档，随实际使用中的失败点不断进化

九大 Skill 分类体系

Anthropic 团队将内部所有 skill 归纳为 9 个类别，这个框架本身具有很强的参考价值：

类别	核心功能	典型示例
Library & API Reference	内部库/CLI/SDK 的正确用法与陷阱	`billing-lib`, `platform-cli`
Product Verification	驱动运行中的产品进行端到端验证	`signup-driver`, `checkout-verifier`
Data & Analysis	连接数据栈与监控体系	`funnel-query`, `grafana`, `datadog`
Business Automation	多工具工作流一键化	`standup-post`, `weekly-recap`
Scaffolding & Templates	框架正确的代码脚手架	`new-app`, `new-migration`
Code Quality & Review	代码质量方法论	`adversarial-review`, `code-style`
CI/CD & Deployment	安全地提交、推送、部署	`babysit-pr`, `deploy-service`
Incident Runbooks	症状→调查→报告的故障处理	`oncall-runner`, `queue-debug`
Infrastructure Ops	带安全门的运维操作	`orphans`, `cost-investigation`

值得注意的洞察：

Product Verification 被特别强调为”对 Claude 输出质量影响最大、最可量化的 skill 类别”，团队认为值得投入一名工程师一周时间专门打磨
Infrastructure Ops 涉及破坏性操作，因此强调”safety-gated”（带安全门）的设计，体现对 AI 自主执行风险的操作性思考

编写 Skill 的四大最佳实践

1. Don’t state the obvious（不要陈述显而易见的内容）

Claude 已经会编程、会读代码。Skill 的价值不在于重述基础能力，而在于提供能将其推出默认思维模式的特殊知识。

正面案例：前端设计 skill 不是教 Claude 怎么写 CSS，而是通过迭代训练其”设计品味”，明确避免 Inter 字体和紫色渐变等陈词滥调。

2. Build a gotchas section（建立”陷阱”章节）

这是文章强调的最高信号价值内容。Gotchas 应来自 Claude 实际使用中的失败点，持续积累。

示例：

“subscriptions 表是 append-only 的，你要找的是 version 最高的行，不是 created_at 最新的”

“Staging 环境即使 Stripe webhook 没实际处理也会返回 200，要查 payment_events 看真实状态”

3. Use the file system and progressive disclosure（利用文件系统实现渐进式披露）

Skill 是一个文件夹，而非单个 markdown 文件。通过 SKILL.md 作为 hub（枢纽）进行调度，具体工作由 spoke（辐条）文件完成。

示例：queue-debugging/SKILL.md 仅 30 行，通过症状匹配表分派到 stuck-jobs.md、dead-letters.md 等具体文件。

4. Avoid railroading Claude（避免过度指令化）

Skill 应提供信息而非 rigid procedure（僵化流程）。对比示例清晰：

过度指令化：Step 1 运行 git log → Step 2 运行 git cherry-pick → Step 3…
更好的方式：“Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can’t land cleanly, explain why.”

一个精妙的工程技巧：动态配置

文章展示了 standup-post skill 中利用 !…“ 语法在 Claude 读取 prompt 前执行 shell 命令的技巧：

!`cat ${CLAUDE_SKILL_DIR}/config.json 2>/dev/null || echo "NOT_CONFIGURED"`

这实现了首次使用时的交互式配置：如果未配置，询问用户 Slack 频道和格式偏好，然后写入 config.json；后续直接复用。这是一种轻量级的 skill 状态管理机制。

深层启示：AI 时代的”组织知识管理”

这篇文章的深层价值在于它揭示了一个趋势：AI coding assistant 的竞争正在从模型能力转向组织知识工程。

不是”AI 能写多少代码”，而是”AI 能正确调用多少内部 API、遵循多少团队规范、避免多少已知陷阱”
Skill 本质上是将组织的 tribal knowledge（部落知识）转化为 machine-readable context 的基础设施
文件系统作为”上下文工程”的载体，比单个 prompt 更接近软件工程的本质——模块化、可维护、可演进

总结

这篇博客是一份高质量的工程实践文档，没有空洞的理论，全部来自 Anthropic 内部 Claude Code 团队的实际经验。它的核心贡献在于：

提供了一套可操作的 skill 分类框架（9 大类别），帮助团队系统化地识别知识缺口
明确了 skill 编写的反模式与正模式（避免重述基础能力、聚焦 gotchas、避免过度指令化）
展示了文件系统作为 AI 上下文工程基础设施的设计思路

对于正在构建或优化 AI 编程工作流的团队，这篇文章提供了从”用 AI 写代码”到”用 AI 正确地、符合组织规范地、可验证地写代码”的进阶路径。