Lessons from Building Claude Code: How We Use Skills

Anthropic (Thariq @trq212, Claude Code 工程师) · 2026-03-18 · Original

来源: Anthropic (Thariq @trq212, Claude Code 工程师) | 日期: 2026-03-18 原文: Lessons from Building Claude Code: How We Use Skills 微信译文: 硅基心脏精读日期: 2026-03-18

一句话总结

Skills 不是 prompt，是给 AI 的操作手册——核心价值在于 Gotchas（踩坑记录）、可执行代码、和渐进式信息披露，而不是流程描述。

核心内容

Skill 的本质：文件夹，不是 Markdown

Skill 是一个文件夹，包含主说明 + scripts/ + references/ + assets/ + config.json + 数据文件。整个文件系统是上下文工程（Context Engineering）的工具——主 md 保持精简，Claude 按需读取子文件，避免一次塞入过多信息。

9 类核心 Skill（按工程团队视角）

类型	代表示例	特点
环境诊断	doctor-check, onboarding	新人上手、验配置
端到端测试	checkout-verifier, auth-flow	模拟真实用户流程
数据获取分析	funnel-query, grafana	连接数据/监控系统
业务流程自动化	standup-post, weekly-recap	把重复工作变成一条命令
代码脚手架	new-migration, create-app	生成框架代码
代码质量审查	adversarial-review, code-style	子 agent 循环批判
CI/CD 部署	babysit-pr, deploy-service	监控 PR 到自动回滚
运维手册	oncall-runner, log-correlator	症状→多工具排查→报告
基础设施运维	resource-orphans, cost-investigation	破坏性操作需防护

写好 Skill 的核心技巧

只写 Claude 不知道的：Claude 对编程有大量默认判断，Skill 要聚焦于「让 Claude 跳出常规思维」的信息。例如 frontend-design skill 专门对抗 Inter 字体 + 紫色渐变这类 AI 审美惯性。

Gotchas 章节是信噪比最高的部分：从 Claude 真实踩坑积累，随时更新。这是整个 Skill 最值钱的内容，不是流程说明。

把文件系统当渐进式披露工具： - references/api.md — 详细函数签名，按需读取 - assets/ — 模板文件，直接复制 - 脚本和辅助库 — 给 Claude 可以直接跑的代码

Description 是触发器，不是摘要：Claude Code 启动时扫描所有 Skill 的 description 来判断路由。要写「什么情况下触发」，不是「这个 Skill 做什么」。

给出信息，留出灵活度： - ❌ 不要说「先做 X，再做 Y，再做 Z」 - ✅ 要说「目标是 A，通常用到 X、Y、Z，请根据实际情况判断」

用配置文件做初始化：需要用户提供上下文的 Skill，把配置存 config.json，未配置时主动询问。

Skill 记忆：Skill 可以维护状态文件（log / JSON / SQLite）。standup-post 记录历史站会，下次运行时读增量变化。数据存 ${CLAUDE_PLUGIN_DATA}，升级 Skill 时不丢失。

按需 Hooks：Skill 级别的 hooks 只在该 Skill 激活时生效。如 /careful 防误删生产数据，平时关闭不影响速度。

分发与治理

小团队：直接提交到 ./.claude/skills/ 仓库
大团队：内部 Plugin 市场，成员自行安装，避免全量上下文膨胀
质量控制：太容易创建低质量重复 Skill，正式发布前要有审核

金句摘录

“A skill is a folder, not just a markdown file. You should think of the entire file system as a form of context engineering and progressive disclosure.”
“The highest signal-to-noise content in any skill is the Gotchas section.”
“The description field is not a summary — it’s a trigger condition.”
“Most of our skills started out as a few lines of text and a gotcha, and got better as people kept adding to them as Claude hit new edge cases.”

Justin 视角

投资视角：这篇文章本质上是 Anthropic 在公开展示「如何把 AI 深度嵌入工程团队」的最佳实践。对于被投企业的 CTO/工程 VP，这是非常直接可落地的 playbook。AI 工具落地深度正在从「用 Copilot 补全代码」升级到「用 Skills 自动化整个工程工作流」，这个跃升需要工程文化配套，不是纯工具问题。

与当前关注的关联： - Skills 的 Gotchas 机制 = 知识资产沉淀，这正是企业版 AI 的核心壁垒（纯 prompt 容易被复制，沉淀的坑点知识不容易） - 「按需 Hooks」+ 「Skill 级记忆」预示着 AI agent 在企业内部的角色从「工具」向「有状态的协作者」转变 - Plugin 市场 + 分发机制暗示 Anthropic 在打企业内部 AI 应用商店的基础设施

可行动 Takeaway： 1. 我们自己的 skills（storybook、GTD、deep-read）应该把 Gotchas 系统化，而不是散落在日记里 2. 所有 Skill 的 description 要重写成触发条件句式 3. draw.py / layout.py 这种「给 Claude 可执行代码」的做法是正确方向，继续深化