Claude Code 的 Skills：AI Agent 真正需要的不是提示词，而是组织记忆

你有没有想过为什么你用了那么多 AI 工具最后还是觉得差点意思一、一个扎心的事实2026 年 6 月 3 日Anthropic 的技术团队成员 Thariq Shihipar 发了一篇博客。文章名字叫《Lessons from building Claude Code: How we use skills》。翻译过来就是我们在 Claude Code 里怎么用 Skills 的。这篇文章没有什么惊天动地的新概念。但它透露了一个信号Skills 已经成为 Claude Code 最常用的扩展点之一Anthropic 内部有数百个 Skills 处于活跃使用状态。什么意思就是说Claude Code 这个面向编程和工程任务的 AI Agent 产品它最核心的能力增强方式不是靠调参不是靠微调不是靠更长的系统提示词。而是靠一个叫 Skills 的机制。二、你对 Skill 的理解可能从一开始就错了很多人看到 Skills第一反应是哦不就是更长的提示词吗把提示词存成文件然后让 AI 读取这有什么新鲜的错。这种理解方式会让你错过 Claude Code 团队这篇文章最尖锐的地方。Skills 不是提示词。它是一个文件夹。这个文件夹里可以有指令、脚本、参考资料、模板、图片、历史日志和配置文件。SKILL.md是入口但不是全部。更重要的是Agent 可以动态发现这些文件夹在需要的时候读取或执行其中的内容。这才是关键。普通提示词像一次口头指挥。你今天说一遍明天还要说一遍。换个同事来还得再说一遍。Skill 不一样。它把重复出现的工作经验固化下来变成一个可复用的系统。提示词让模型听话Skill 让模型进入一个可复用的工作现场。三、九类 Skills把隐性知识装进正确盒子Claude Code 团队盘点内部 Skills 后把它们分成了九类1.Library and API reference- 库和 API 参考2.Product verification- 产品验证3.Data fetching and analysis- 数据获取和分析4.Business process and team automation- 业务流程和团队自动化5.Code scaffolding and templates- 代码脚手架和模板6.Code quality and review- 代码质量和审查7.CI/CD and deployment- 持续集成、交付和部署8.Runbooks- 故障处理手册9.Infrastructure operations- 基础设施运维这个分类本身不重要。重要的是它背后的逻辑一个好 Skill 应该足够窄。如果一个 Skill 同时想做 API 文档、代码审查、部署、监控、写周报它就会让 Agent 不知道该按哪套规则行动。模型不是没有能力而是被过宽的上下文推向了模糊。最有价值的 Skill 不是最完整的而是最能约束一个具体失败场景的。四、验证类 Skill最被低估的能力在这九类里Product verification产品验证是最值得展开说的。为什么因为 Agent 最危险的错误常常不是什么都没做而是看起来做完了。你让 Agent 改一个结账页面。它写完代码后告诉你已修复。但真正的问题是用户能不能从购物车走到付款成功Stripe 的测试卡有没有触发正确账单订单状态有没有进入数据库里正确的字段验证类 Skill 把这些问题变成脚本、断言和证据。它可以让 Claude Code 运行浏览器测试记录输出视频检查每一步状态。Agent 的质量不只来自生成能力还来自被验证能力。这才是 AI 工程的核心。不是让模型多写代码而是让模型进入一个有反馈、有断言、有证据的工作回路。五、Gotchas把团队踩过的坑写进系统Claude Code 团队在文章里有一句很硬的判断不要陈述显而易见的事。这句话值得反复看。很多人写 Skill会写成这种内容• 写代码前先理解需求• 保持代码简洁• 修改后运行测试• 遇到错误要调试这些话不是错。问题是 Claude 本来就知道。你把它们写进 Skill只是在增加上下文成本。真正高价值的是 Gotchas。Gotchas 是具体坑点。它不是抽象原则而是团队真的踩过、模型也容易踩的失败模式。比如• 某张subscriptions表是 append-only。你要找当前订阅状态不能只看最新创建时间而要看版本号最高的那一行。• 同一个请求 ID在 API gateway 里叫request_id在 billing service 里叫trace_id。两个名字不同但指向同一条请求链路。• staging 环境返回 200不代表 Stripe webhook 真被处理了。真正状态还要查payment_events表。这些内容才是组织知识。它们不是最佳实践。它们是错误为什么会发生以及如何不再发生。真正的组织知识往往不是宏大的原则而是错误不会重复发生的理由。六、Progressive Disclosure上下文工程的底层逻辑Claude Code 的 Skills 机制有一个核心设计progressive disclosure。翻译成大白话就是不要一次把所有资料都塞进模型。先让模型知道有哪些能力等任务需要时再逐层打开对应内容。这个机制分三层第一层metadata。Claude Code 启动时只看到 Skill 的名称和描述。第二层SKILL.md。当任务触发这个 SkillClaude 才读取里面的完整说明。第三层references、scripts、assets。比如references/api.md放 API 细节scripts/validate.py放验证脚本。模型不需要每次都读完所有文件。它只在需要时取用。这就是上下文工程的底层思路。上下文工程不是把 prompt 写长。上下文工程是设计一个系统让模型在正确时间接触正确材料。上下文工程的本质是让模型少读无关内容多接触关键事实。七、从个人技巧到组织能力一个 Skill 写出来只是第一步。更难的问题是谁会用怎么分发怎么更新怎么防止过期Claude Code 团队给出两种方式小团队把 Skills 提交进项目仓库路径通常是.claude/skills。大团队使用 Claude Code Plugin marketplace也就是内部插件市场。团队成员可以按需安装 Skills。Anthropic 内部没有让一个中心团队预先决定所有 Skill 的生死。他们让有用的 Skill 先在 sandbox 文件夹、GitHub 或 Slack 里流动。等 Skill 得到足够使用再通过 PR 进入 marketplace。这很像开源包生态。不是先设计一个完美知识库而是让真正有用的能力自然浮上来。一个 Skill 被写出来只是开始。被正确触发、被持续维护、被团队采用才算进入生产。八、风险能力包也可能变成攻击面Skill 越强风险越不能忽略。Anthropic API 文档明确提醒Skills 应该只从可信来源使用。因为 Skill 不只是文本它可能包含脚本、外部资源和工具权限。如果一个未经审计的 Skill 要求模型读取敏感文件、调用网络接口、执行 shell 命令它就可能造成数据泄露或系统破坏。外部 URL 也是风险点。如果 Skill 会抓取网页内容而网页里藏着恶意指令模型可能把那些内容误当成任务指令。所以Skill 应该像软件依赖一样管理。它需要审计需要版本需要测试需要权限边界需要下架机制。一旦 Skill 能调用工具它就不再只是文档而是供应链的一部分。九、一套可落地的 Skill 构建法读完 Claude Code 这篇文章不是让你马上创建十几个 Skills。更好的做法相反。先找一个 Agent 每周反复做错的任务。这个任务最好满足三个条件• 高频• 边界清晰• 能验证结果比如• 每次改支付流程都忘记查事件表• 每次写迁移都漏掉回滚约束• 每次查日志都混淆request_id和trace_id• 每次发 PR 都忘记跑某个内部 verifier然后只为这个任务写一个窄 Skill。第一版SKILL.md不需要宏大。它只需要回答几个问题• 这个 Skill 在什么任务里触发• 模型通常会犯什么错• 正确流程是什么• 哪些检查必须执行• 哪些脚本可以减少不确定性• 结果如何证明如果这一个 Skill 能稳定减少错误再考虑第二个。好 Skill 不是把人类的话写长而是把人类反复纠错的成本写低。十、写在最后Claude Code 这篇文章最重要的启发是把我们从 prompt 思维推到系统思维。Prompt 思维会问我该怎么把话说得更清楚Skill 思维会问这件事为什么每次都要人类重新提醒哪些知识可以固化哪些步骤可以脚本化哪些结果必须验证哪些错误应该写进 Gotchas这个能力如何被团队分发这两个问题不在同一个层级。前者关心一次对话。后者关心一套工作机制。所以真正值得做的 Skill不是提示词收藏夹。它应该是一个小而硬的工程单元有触发条件有失败记忆有参考资料有脚本有验证有分发路径。当一个团队把这种东西持续积累起来Agent 才不只是一个会写代码的助手。它开始接触团队真正的工作现场。参考来源1. Claude Blog, “Lessons from building Claude Code: How we use skills”, 2026-06-032. Claude Code Docs, “Extend Claude with skills”3. Claude API Docs, “Agent Skills”4. Claude API Docs, “Skill authoring best practices”5. Agent Skills standard6. Anthropic Engineering, “Equipping agents for the real world with Agent Skills”, 2025-10-167. GitHub,anthropics/skills8. Claude Blog, “A harness for every task: dynamic workflows in Claude Code”, 2026-06-02