本文由 莫潇羽@无忆研习社（www.wuyi.wiki）撰写，转载请注明出处。

快速摘要

先把结论摆在最前面：Claude Code 不是又一个能写代码的聊天框，而是一个直接在终端里替你改文件、跑测试、提交代码的命令行编程搭档；Agent Skills 则是给它——以及 Codex、Trae、CodeBuddy 这些同样支持该标准的工具——外挂的「技能包」，用一份 SKILL.md 加上可选的脚本和参考文档，把你脑子里的专业流程沉淀成 AI 能反复调用的能力。两者的关键词其实是同一个：把「给你提建议」升级成「替你把活干完」。

这篇我会从最基础的安装、命令、四种工作模式讲起，把 CLAUDE.md、Git/GitHub 集成、MCP、自定义命令这些日常高频的东西一个个拆开；然后进到 Agent Skills，把它的三层渐进式加载原理、目录结构、从零搭建到跨平台部署完整走一遍；最后再深入一层，聊聊从工程角度看这类工具为什么稳、它的自修复和上下文压缩思路怎么搬到你自己的 Agent 上，以及插件系统和绕不开的安全话题。

内容偏长，是我自己一段时间折腾下来的实践笔记，新手也能跟着上手。想看完整拆解，往下翻。

一、先把 Claude Code 到底是什么讲清楚

刚接触的人很容易把它和别的工具划等号，但用过一阵你会发现它走的是另一条路。

1.1 它和 Cursor、通义灵码这类工具差在哪

我们之前用得多的 AI 编程工具，大多带一个图形界面：左边是文件树，中间是编辑器，你选中一段代码，在侧栏对话框里提问，它给你一段补全或一条修改建议，你点接受。Cursor、通义灵码、CodeBuddy 大致都是这个路子，本质上仍然是「人在驾驶，AI 在副驾给提示」。

Claude Code 反过来。它完全跑在终端里，没有自己的图形编辑界面，你看到的就是一个命令行对话框。你输入一句自然语言——比如「帮我修一下登录接口的空指针问题」——它会自己去读项目里的文件、定位问题、改代码、跑测试，整条链路它自己走完。这种交互一开始会让人不太习惯，毕竟没有按钮可点，但效率确实高，因为中间那些「你点一下、它再动一下」的来回被省掉了。

差别说白了在自动化程度。带界面的工具因为有可视化的确认环节，很多场景下是半自动的，需要你不断介入；Claude Code 把这一层默认收了起来，它能分析整个代码库、理解项目架构，然后端到端地把一个任务执行完。它的底层就是一个 agent——会拆任务、会调工具、会根据结果决定下一步——这是它和「补全式」工具最根本的不同。

1.2 一句话定位：会动手干活的搭档

我自己给它的定位是：它已经不只是编码工具了，而是一款生产力工具。它的适用人群也不局限于个人开发者——技术团队、甚至偏管理的角色都能用，因为它能覆盖从需求理解、方案规划到代码实现、测试、审查的全流程，而不只是「写一段函数」。

一句话总结这一节：以前的工具给你建议，Claude Code 直接帮你把事做了。理解了这个定位，后面所有的命令和模式才有意义。

二、安装与第一次启动

2.1 三种常见安装路径

官方给的安装方式有好几种，最省事的是用包管理器全局安装。装完之后在终端敲一下版本号确认没问题，就可以用了。我个人建议优先装最新版本，很多奇怪的小问题在新版里其实已经修掉了，遇到命令不识别、报错的情况，第一反应先看版本对不对。

Windows 用户这里有个常见坑：官方的安装命令分 PowerShell 和 CMD 两套写法，贴错了会提示 'irm' is not recognized 或者 && 不是有效分隔符之类。看到这种报错别慌，多半是终端环境贴错命令了，对着官方文档(code.claude.com/docs)把对应环境的那条复制过去就行。

2.2 第一次进入：claude 命令与信任目录

安装好之后，进入你的项目目录，直接敲：

claude

它会先问你是否信任当前目录，回车确认就进了交互界面。界面很干净，就是一个输入框。你也可以启动时直接带上问题：

claude "分析这个项目的整体结构"

这样它进来就直接开始干活，省掉一步。终端用 Windows 自带的 CMD 可以，但我更推荐用体验好一点的终端工具（比如 Windows Terminal），中文显示和交互都顺一些。

2.3 集成进 VS Code / Cursor / Trae

如果不想纯在命令行里折腾，可以把它集成进编辑器。在 VS Code 或 Cursor 的扩展市场里搜 Claude Code 的官方插件装上，装完编辑器里会多一个图标，点开就是一个带对话窗口的面板。这个面板底层还是命令行那套，但多了可视化的展示，调用细节看得更清楚。我自己写复杂任务时喜欢用这个面板版，能更直观地看到它每一步在读哪个文件、执行哪条命令。

提醒一句：早期在 Python 等环境里直接装的那个版本可能比较老、还是纯命令行；VS Code、Cursor 里的插件版本通常升级过，体验更好。把 Claude Code 集成进 Cursor 这类工具，两边结合着用，效果会比单用一个强不少。

三、必须先记住的基础命令

这些斜杠命令是你和 Claude Code 打交道最高频的东西，掌握了它们，使用体验会顺很多。下面我先用一张表把常用的几个列出来，再挑重点说几句。

3.1 上下文管理：/clear 与 /compact

这两个最常用。聊得久了，上下文越堆越长，模型的注意力会分散，开始出现「你以为它懂了，结果执行起来偏到姥姥家」的情况。/clear 是直接把当前上下文清掉重开，干净利落；/compact 则是把对话压缩一下——你可以理解成把一长串聊天「蒸馏」成一份摘要，关键信息留着，啰嗦的过程砍掉，既避免溢出又不至于把背景全丢了。

我的习惯是：发现它方向开始不对，先 /clear 重启再换个说法；如果只是历史太长但任务还得接着做，就 /compact。

3.2 看花了多少 token：/cost

如果你用的是按量计费的 API 或者免费额度，养成随手 /cost 的习惯很有必要。它会告诉你这场对话累计用了多少 token、大概花了多少钱。在长会话或者密集生成代码的时候，偶尔瞄一眼，发现飙升就及时提更具体的问题、压缩上下文，能省下不少开销。

3.3 切换模型：/model

/model 会弹出可选模型让你挑。Claude 系列一般分几个档：默认那款均衡，速度和能力兼顾，日常用它就够；还有更强但更贵的款，适合啃复杂问题；以及成本最低、速度最快但效果相对弱的款。大部分时候默认款足矣，遇到硬骨头再切最强款。

3.4 配置与初始化：/config 与 /init

/config 是交互式改配置，主题、自动压缩开关、编辑模式都能在里面调。/init 更重要——它会扫描你的项目，自动生成一份 CLAUDE.md。这份文件是后面整个工作流的基石，下一章专门讲它。

3.5 几个进阶但很实用的命令

再补几个我用得上的。会话管理这块，/resume 能切回历史会话，你之前开过的多个对话都列在那儿，想接着哪个聊就挑哪个；/rename 给会话改名，方便区分。还有个回滚功能，能把会话退回到之前某一步的状态——它一通操作之后你觉得改歪了，不用从头来过，退回去重来即可。

命令行层面，claude -c 可以恢复到上一次的对话（continue），适合你不小心关掉终端、或者卡死了看不到结果，重进接着干；claude -r 则是从历史里挑一个会话恢复（resume）。这两个我踩过坑：以前不知道，会话一断就重头来，知道之后省了不少事。

最后提一个进阶玩法——无头模式（headless）。前面进的都是交互界面，其实加个 -p 参数就能把它当纯命令行工具用：

# 直接出结果，不进交互界面
claude -p "解释一下这个文件做了什么" < some_file.py
# 也能接管道，把日志丢给它分析
cat logs.txt | claude -p "找出其中的异常"

加了 -p 它不进对话界面，直接给你答案，还能指定 JSON 格式输出。这种模式适合脚本自动化、CI/CD 流程——你想把 Claude Code 的能力嵌进自动化部署里，就用它。日常交互我们用界面版，需要把它当一个「输入进、结果出」的工具时，无头模式更顺手。

四、四种工作模式，决定了你「放手」的程度

Claude Code 写代码时，到底要不要每一步都等你点头？这由工作模式决定。按 Shift+Tab 可以在几种模式间切换，搞清楚它们，你才能拿捏「什么时候让它自动跑、什么时候必须人盯着」。

4.1 默认询问模式

最稳的一档。它每要执行一个有副作用的动作（改文件、跑命令）前，都会停下来问你一句「要继续吗」，你确认它才动。修历史项目的 bug、在陌生仓库里排查问题时，我都用这个，宁可多点几下，也不想它瞎改。

4.2 自动编辑模式（Shift+Tab）

按 Shift+Tab 切到自动编辑，它就不再为每次编辑停下来问你了，会连续地把活干完。适合那种你已经看明白方向、信任它能稳定输出的重复性工作。

4.3 计划模式：只出方案不动手

这是我个人很喜欢的一档。在计划模式（Plan Mode）下，Claude Code 只给方案、列步骤、做技术调研，但不真正动手改东西。前期做需求分析、架构规划、风险点梳理特别合适——先让它把思路理清楚，你审一遍方案，觉得没问题再切到执行模式让它干。把「思考」和「执行」分开，返工率会低很多。

4.4 全自动模式（YOLO）的边界

还有一档叫 YOLO 模式，对应命令行参数 --dangerously-skip-permissions（官方称之为 Safe YOLO mode）。开启后它跳过所有权限确认，不间断地一路干到底，完全不需要你介入。

claude --dangerously-skip-permissions "只修复 src/components 目录下的类型错误"

效率拉满，但这里我必须把丑话说前面：这个参数名里专门带了 dangerously 就是在提醒你。它没有任何兜底，官方文档原话是它对提示注入和误操作「不提供任何保护」。所以我的建议很明确——

• 别拿它当日常默认。带密钥的终端、能连内部服务、能部署或删数据的真实环境，统统不要开。
• 真要用，把范围说清楚（像上面那条只限定一个目录），别写「优化整个项目」这种大而空的指令。
• 最好在隔离环境（比如 Docker 容器）里跑，把文件系统访问范围限死。
• 日常想偷懒少点几下确认，更稳的做法是用 /permissions 把 lint、test、git 这类安全常用命令预批准，配合 .claude/settings.json 做精细化白名单——这是有意识的安全决策，而不是把安全门整个关掉。

记住一句话：沙箱定义的是边界，而不是「绕过所有检查」。模式选对，才敢真正放手。

五、CLAUDE.md：给 Claude Code 立规矩

5.1 它到底是什么

CLAUDE.md 是 Claude Code 的「全局记忆」文件，相当于一份给它看的使用规则说明书。你可以把项目的开发规范、代码风格、命名约定、允许执行的命令、核心文件说明都写进去。它在工作时会自动读取并参考里面的内容，生成的代码就会按你定的规矩来。

这东西的价值在于一次写好、反复生效，省得你每次对话都重复交代一遍「这个项目用 4 空格缩进、函数名用驼峰、写完要跑测试」。

5.2 三个层级：项目级 / 用户级 / 本地私有

CLAUDE.md 可以放在不同位置，对应不同的生效范围：

• 项目根目录的 CLAUDE.md：跟着项目走，团队成员都能共享这份规范，提交进仓库给大家用。
• 用户级（~/.claude/CLAUDE.md）：跟着你这台机器的登录用户走，你打开的所有项目都生效。
• 本地私有（CLAUDE.local.md）：写一些你个人的小工具、小习惯，但又不想推给团队，就写这个文件，再用 .gitignore 忽略掉，不上传。

它们之间是叠加关系：不同目录下的 CLAUDE.md 都会被加进当前上下文，所以你在不同层级写的内容，对应生效的范围会有差异。

5.3 怎么写一份好的 CLAUDE.md

它就是一份 Markdown，结构清晰即可。我一般会包含这几块：

# 项目开发规范

## 代码风格
- 统一使用 4 空格缩进
- 函数、变量命名使用驼峰式
- 必须严格按照 ESLint 规范编写代码

## 工作流程
- 编写代码前先阅读相关模块，理解上下文再动手
- 改完功能后必须运行测试并自检
- 提交时做原子化提交，一个小功能一次提交

## 允许的命令
- 允许执行 lint、test、git 相关命令，无需逐次确认

## 全程使用中文交流

注意我在里面用了「必须」「严格」这类强调词。这是个小技巧：把你最在意的硬要求用强语气写出来，它的遵循度会更高。规范写得越具体，它产出的质量越稳——这点我（莫潇羽）在无忆研习社后台改了好几版规范才慢慢体会到。

5.4 动态上下文注入的小技巧

CLAUDE.md 里还可以放一些动态信息，比如把当前系统时间用一个占位标签写进去，每次加载时拼成最新的上下文。这样它在做与时间相关的任务时，拿到的就是实时信息，而不是一个写死的旧值。这种「上下文注入」的思路，后面讲它内部设计时还会再提到。

六、和 Git、GitHub 打通：让它真的会提交代码

6.1 为什么说它「深度集成开发流程」

普通编程工具帮你写代码，写完你还得自己去建分支、提交、推送、合并。Claude Code 把这一整套也接了进来：你直接提命令，它就能帮你建分支、修 bug、提交代码、合并主分支，全自动完成。这才是「深度集成开发流程」的意思——它不只会写代码，还会做版本控制。

6.2 配置 gh，把仓库操作交给它

要让它自动操作 GitHub，得先装 GitHub 的命令行客户端 gh 并完成授权（登录拿到 token）。配好之后，你就可以在对话里直接让它干活了。比如让它拉一个项目下来：

# 在 Claude Code 对话里直接说：
请使用 gh 命令帮我 clone 这个项目：<仓库地址>

它会自己去调 gh，把项目拉下来，然后你就能让它在里面改东西、再推上去。整条链路它底层都是基于 bash 去整合调用各种命令完成的。

这里顺带说个关于原子化提交的好习惯：让它跟 Git 工作流打通时，规定它做原子化提交——完成一个小功能就提交一次，别攒一大堆再一起提。不然一次提交里塞了一堆改动，万一有 bug 很难定位。重要版本记得打标签。这其实不光是用 AI 工具该注意的，平时手写代码也该这么干，只是现在让工具也按这个习惯来。

6.3 一个常踩的坑：网络与授权

实操里偶尔会遇到项目拉不下来、命令执行报错的情况，多半是网络环境的问题，或者 gh 还没授权登录、没拿到 token。这很正常，多试几次、把凭据配好通常就过了。如果你没开 YOLO 模式，它执行 gh 这类命令时会弹授权确认，这也是为什么前面建议你把常用命令用 /permissions 预批准——配好之后它就不会反复来问你了。

七、MCP：给 Claude Code 接上外部世界

7.1 MCP 是什么（用 USB 类比）

MCP 全称 Model Context Protocol（模型上下文协议）。可能有人没接触过，我用个类比：USB 解决的是「电脑怎么统一接各种外设」的问题——键盘、鼠标、U 盘，只要支持 USB 就能插上被识别。MCP 解决的是「大模型怎么统一接各种外部能力」的问题——访问 API、读本地文件、连企业内部数据库，只要按 MCP 协议实现的服务，都能用一套标准的方式接进来。

它有几种传输协议，常见的有基于 HTTP/SSE 的，也有基于标准输入输出（stdio）的，这些细节先不用纠结，知道它是个「统一接口」就够了。

7.2 claude mcp add 实操

往 Claude Code 里加 MCP 服务，先看看当前有哪些：

claude mcp list

加一个，比如接 Figma 的设计稿（做设计联调很好用）：

claude mcp add --transport http figma https://mcp.figma.com/mcp

加完进 Claude Code，用 /mcp 选中它做鉴权（Authenticate）。之后你把 Figma 设计稿链接粘到需求里，它就能拿到精确的间距、字体、颜色值去生成代码，而不是靠看图片瞎猜。除了 Figma，监控告警类的服务也常接——让它通过 MCP 连上你们的监控系统，自动拉线上报错日志、分析、再去修，这套结合起来用威力不小。

7.3 为什么官方更推荐直接用 CLI

这里有个反直觉的点值得说：能用现成 CLI 工具的场景，往往比 MCP 更省。原因在上下文成本——MCP 服务器的工具定义默认是常驻的，会一直占用上下文空间；而直接调用 CLI（比如 gh、aws、sentry-cli）没有常驻成本，只在调用时产生输出。所以像「用 gh 创建一个 PR」「用 sentry-cli 查最近的错误」这种，直接让它调命令往往比挂一个 MCP 更划算。新版本虽然有工具延迟加载机制缓解了这个问题，但仍建议你别一口气挂一大堆 MCP。

八、自定义斜杠命令：把重复活儿一键化

8.1 在 .claude/commands 下建命令

除了官方内置的斜杠命令，你还能自己加。做法是在项目的 .claude 目录下建一个 commands 目录，在里面放一个 Markdown 文件，文件名就是命令名。退出重进让它重新加载，你的命令就出现在斜杠列表里了。

8.2 一个「自动修 bug」的命令示例

举个我用得顺手的例子——做一个传入 issue 编号就自动修 bug 的命令。文件内容大致是这样的指令模板：

# fixissue

接收一个 issue ID 作为参数，自动完成以下流程：
1. 用 gh 命令拉取该 issue 的描述
2. 在代码库中搜索相关文件，定位问题
3. 修复代码并运行测试验证
4. 通过质量检查与类型检查
5. 提交并创建 PR

之后你只要 /fixissue <编号>，它就会自动分析 issue、搜代码、定位、修复、验证、提交一条龙。这相当于把你平时改一个线上问题的标准流程，封装成了一键操作——这其实已经很接近后面要讲的 Skill 思路了。

九、把效率拉起来的实战场景

讲完基础，来点我自己跑下来觉得最能体现价值的场景。

9.1 大型项目改造

在大型项目改造上，它能明显压缩工期。原来按部就班一步步来要三五天的活，把流程拆开并行——技术栈规划用一个实例、需求分析用一个实例、代码修改交给它跑、最后人工介入做质量把关——熟练之后整体效率能提到三到四倍。这里强调「熟练」：前期你得先把各种细节、常见坑摸清楚，刚上手别指望直接起飞，先做好入门，再谈效率。

9.2 边开会边出 demo

一个挺爽的用法：开两小时的需求评审会，你不是主讲，那这段时间别浪费。会上产品讲到的需求，你随手喂给 Claude Code 让它并行生成 UI、画页面，需求有变动就实时更新进去。等会开完，demo 也差不多出来了，所见即所得。这叫会议中的高效编码——开发和会议并行，散会直接看效果。

9.3 前端 bug 自动定位与修复（Playwright + MCP）

前端那种「某个页面展示不对」的 bug，可以装 Playwright（浏览器自动化工具）的能力，通过 MCP 打通，让 Claude Code 自动刷新页面、分析前端报错、找到 bug、改代码、再发布测试，全自动闭环。原来需要人工复现、改代码、回归测试可能两小时的活，全自动加上 Playwright 之后大概二十分钟就能搞定。这就是真正意义上的全自动调试，而不是只帮你改一段代码。

9.4 快速读懂一个开源项目

学习一个动辄几万行的开源项目，时间成本很高。你可以把仓库地址丢给它：

请帮我分析一下这个项目实现了哪些功能，仓库地址：<地址>

它会自动拉下来、分析架构、讲解模块，你还能问得很细——某一行代码里某个函数干了什么都能问。更关键的是，做涉密或安全要求高的项目时，让它顺手扫一遍有没有高危漏洞，比你自己一行行啃靠谱得多。原来要几天的学习加开发，压缩到几个小时，质量还有它那套自动审查、测试流程兜着。这让 Claude Code 不只是编程工具，更像一个学习工具——比单纯问大模型强在它能真去「做事」，而不只是问答。

9.5 多实例并行：把它当一个小团队

你可以同时开多个 Claude Code 窗口，每个窗口一个独立对话，数量不限。一个写代码、一个做验证、一个做运维部署，就像模拟一个团队在协作。微服务开发场景特别适合：每个服务一个文件夹，每个实例负责一个服务，各自配自己的分支和工作目录。屏幕切四块，左上前端、右上后端、左下性能优化、右下文档编写，八小时的并行产出能顶好几天。这才是真正的「AI 编程」，而不是用工具提两条建议就完事。

这几个场景跑下来，我最大的体会其实是一个不起眼的细节：提示词写得越具体，结果质量越高。同样是让它加个功能，你写「添加日历小部件」和写清楚「在首页右上角添加一个月视图日历小部件，支持点击日期切换、数据从 /api/events 拉取」，出来的东西天差地别。写得泛，它就只能猜；写得细，它就按你的需求精确实现。所以别嫌麻烦，把需求、约束、预期输出交代清楚，这是用好它最关键的一个习惯。遇到它方向跑偏，随时按 ESC 终止，调整提示词再让它继续，比硬等它跑完一堆错的东西强。

十、从「写提示词」到「造技能」：为什么需要 Agent Skills

前面讲的都是 Claude Code 本身。从这一章开始，我们进到一个更有意思的话题——Agent Skills（技能）。它现在很火，原因得从一个痛点说起。

10.1 长提示词的三个老毛病

很多人做 agent，习惯把一切塞进一份几百行的系统提示词里，试图定义一个全能助手。简单测试时它表现挺好，可一旦进到复杂业务流程，问题就冒出来了。归根到底是三个毛病：

第一，注意力涣散。提示词写得越长、对话轮次越多，上下文越长，模型的注意力机制（底层是 Transformer 的 attention）在长文本里就会分散、迷失，开始忽略你的细节要求，甚至冒出莫名其妙的话——也就是幻觉。

第二，流程失控。你把一个大任务一股脑写进去、步骤又乱又长，没拆细，它执行起来就到处出岔子，缺乏跨步骤维持逻辑一致性的机制。

第三，工具调用混乱。工具库没定义清楚、定义又冗长，模型经常找不到工具、乱调工具，而且每个工具的定义本身就吃掉大量 token。

这些问题的本质，是我们在用「线性的文本」去控制「多维度的复杂工程」，错配了。

10.2 Skill 到底是什么

Skill 翻译过来就是「技能」，跟玩游戏里的技能一个意思——封装一个特定能力。但它比一份提示词强在哪？它是一个有组织的文件夹，由几部分组成：

• 一份核心的 SKILL.md，是这个技能的「说明书」，描述它用在什么场景、有哪些步骤、注意事项。
• 可选的脚本（scripts），让它能执行真实代码——上传文件、调 API 这种大模型自己干不了的事。
• 可选的参考文档（references），相当于一个按需调用的知识库。

把它类比成给新员工的一份「入职指南」：通用 agent 是个能力很强但什么规矩都不懂的新人，Skill 就是把你公司的流程、规范、工具说明打包好交给它，让它瞬间变成「懂行的专家」。一句话——Agent Skills 不是一段简单脚本，而是一套「SOP（标准作业流程）+ 工具 + 知识库」的组合。

值得一提的是，Agent Skills 是一套开放标准（2025 年底正式确立），不只 Claude Code 支持，OpenAI 的 Codex CLI、ChatGPT，以及国产的 Trae、CodeBuddy 等都采用了同一份格式。这意味着你写好一个 Skill，可以在多个平台上跑，迁移成本极低。

10.3 Skill、Function Calling、MCP 的边界

这三个概念容易混，我用做菜打个比方：

看出区别了吧：MCP 解决的是「工具调用、数据连接」，是一把好用的刀；Skill 解决的是「一整套标准流程」，是教你怎么把这道菜做出来的菜谱。实际用的时候，它俩经常结合——Skill 里调用 MCP 工具，是常见组合。

十一、Skill 的结构与渐进式加载原理

这一章是整篇里我觉得最该理解透的地方，因为它解释了 Skill 为什么能在「能力深度」和「上下文成本」之间取得平衡。

11.1 一个 Skill 的目录长什么样

一个标准 Skill 就是一个文件夹，结构大致如下：

my-skill/
├── SKILL.md        # 主指令文件（唯一必需）
├── scripts/        # 可执行脚本（可选）
│   └── upload.py
├── references/     # 参考文档，按需加载（可选）
│   └── finance-handbook.md
├── assets/         # 模板、图片等资源（可选）
│   └── template.html
└── examples/       # 示例输出（可选）
    └── sample.md

记住一点：SKILL.md 是唯一必需的，其余都是可选的。多个 Skill 就建多个文件夹，互相隔离。在 Claude Code 里，这些 Skill 放在 .claude/skills/ 目录下；不同工具的目录约定略有差异，第十三章会讲。

SKILL.md 的开头是一段 YAML frontmatter，只有两个关键字段：

---
name: meeting-summary
description: 用于会议纪要的智能生成与文档自动同步
---

# 会议总结助手

## 总结规则
对会议内容按「参会人员 / 议题 / 决定」等维度逐条提炼……

## 上传规程
当提到「上传 / 同步 / 推送到云端」时，调用 scripts/upload.py……

name 和 description 这两行非常关键，它们就是下面要讲的「第一层加载」。

11.2 三层渐进式加载（L1 / L2 / L3）

Skill 的核心机制叫渐进式披露（Progressive Disclosure）——模型不会一上来把所有内容都塞进上下文，而是分三层按需加载，像一本组织良好的手册：先看目录，再翻章节，最后才查附录。

flowchart TD
    A["L1 元数据层<br/>name + description<br/>≈100 tokens，启动即加载"] --> B["L2 主体说明<br/>SKILL.md 正文<br/><5k tokens，触发时加载"]
    B --> C["L3 资源与代码<br/>references / scripts<br/>按需加载，命中才读"]

具体来说：

• L1 元数据层：启动时，模型只把每个 Skill 的 name 和 description 预加载进系统提示词，大约只占 100 个 token。它的作用是让模型知道「我手上有哪些技能、各自管什么」，但不把完整内容读进来。
• L2 主体说明：当模型判断某个 Skill 相关、真要用它时，才去读完整的 SKILL.md 正文，通常控制在 5000 token 以内。
• L3 资源与代码：只有真正需要时，才加载 references 里的知识库文档或调用 scripts 里的脚本。这一层的 token 消耗取决于文档本身有多大。

举个会议纪要的例子：如果这场会没提到资金、采购这类财务话题，它就不会去加载 references 里那份几十页的公司财务手册；只有对话里出现相关关键词，才触发加载。同理，只有提到「上传 / 同步」，才去调 upload.py 脚本。

三层各自吃多少 token，心里有个数会更好把控成本，我大致估算如下（具体随内容浮动）：

一个换算常识：中文一般一个字约占 2 个 token，英文约 1 个 token。所以一份 10KB 的中文知识库被加载时，token 占用是相当可观的——这正是为什么不能让它常驻上下文。

11.3 这套机制到底省了什么

答案是 token 成本和注意力。

设想你给一个 agent 装了上百份公司文档，如果每次对话都把它们全塞进上下文，token 消耗会爆炸，调用成本高得离谱，长文本还会拖垮模型注意力。渐进式加载让它「用到哪份文档才加载哪份」，实测在长链条业务流程里能把上下文 token 消耗降低六到八成，同时还显著提升了长任务里的指令遵循准确率。

所以这套机制的价值是双重的：既省钱，又让模型在该专注的地方专注。理解了这一层，你就理解了为什么大家说「给一个 agent 装一千个技能，平时也几乎不占上下文，只有干活时才调用相关记忆」。

我把它的完整生命周期再串一遍，方便你建立整体印象：

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant S as SKILL.md
    parti