技能的安装位置、读取机制和 Context 中的动态加载

技能从安装到生效的完整旅程

放在哪、怎么被发现、什么时候加载、在 context 里占什么位置

1
技能装在哪？项目级 vs 全局
全局技能
装在用户目录下，对所有项目生效。
不管你打开哪个文件夹，这些技能都在。
适合放"通用能力"：写邮件、搜索网页、数据分析。

就像你手机上装的 App——不管打开哪个聊天，相机 App 都在。
项目级技能
装在项目目录下，只在这个项目里生效。
换一个项目文件夹，这些技能就不在了。
适合放"项目专属能力"：写周报、用公司模板做 PPT。

就像项目文件夹里的工具——只有打开这个项目才能用。
## 全局技能 ——————————————

~/.claude/skills/ ← Claude Code 全局
├── web-search/SKILL.md
└── data-analysis/SKILL.md

~/.codex/skills/ ← Codex 全局（也可在 rules/ 下）
~/.openclaw/skills/ ← OpenClaw 全局
~/.hermes/skills/ ← Hermes 全局（含 auto-generated/）


## 项目级技能 ——————————————

~/my-project/
├── .claude/skills/ ← Claude Code 项目级
│ ├── write-weekly-report/SKILL.md ← 只在这个项目有效
│ └── make-pptx/SKILL.md
├── .codex/skills/ ← Codex 项目级
└── skills/ ← 通用位置（OpenClaw/Hermes 也认）
优先级：项目级 > 全局。如果全局有一个 "make-pptx" 技能，项目里也有一个同名技能，项目里的会覆盖全局的。就像 CLAUDE.md 的层级关系一样——越具体的覆盖越通用的。
2
技能在 Context 里占什么位置？
技能不是一次性全部塞进 context 的——它分两阶段加载，占不同的位置。
Agent 的 Context 窗口
最高
系统指令 始终
框架内置的底层规则
第二
CLAUDE.md / AGENTS.md / SOUL.md 始终
你写的项目规范
第三
⭐ 技能元数据（所有技能的 name + description）始终加载
只有名称和简介！不是全文！Agent 靠这些判断"有哪些技能可用"。
第四
你的对话指令 始终
"帮我写周报""帮我做 PPT"
第五
对话历史
之前的对话来回
动态
⭐ 技能全文（被触发的那个技能的完整 SKILL.md）按需加载
只有被触发的技能才会加载全文！没用到的技能不占 context 空间。
动态
文件内容 + 工具执行结果
读文件、跑命令的返回
这就是为什么你可以装 100 个技能但不会撑爆 context——100 个技能的元数据（名称+简介）可能只占 2000 token，但每个技能全文可能有 3000-5000 token。Agent 平时只看"目录"，用到哪个才打开哪本"手册"。
3
技能是怎么被动态加载的？5 步全流程
Agent 启动：扫描 skills/ 目录
Agent 启动时自动扫描全局和项目的 skills/ 目录，发现所有 SKILL.md 文件。
读取范围：只读 YAML 头部（name + description），不读正文
建立技能目录：所有元数据进入 context
把所有技能的名称和描述加载到 context 的"第三层"。Agent 现在知道"我有哪些技能"，但还不知道每个技能的具体步骤。
context 新增：≈20-50 token × 技能数量（非常小）
你说了一句话：Agent 做技能匹配
你说"帮我写周报"。Agent 拿你的话去比对所有技能的 description，发现 "write-weekly-report" 的描述里有"周报"关键词——命中。
匹配方式：description 里的关键词 + 语义理解
加载全文：被触发的技能完整进入 context
Agent 打开 write-weekly-report/SKILL.md，读取完整内容——所有步骤、门禁、输出模板、案例——全部加载到 context 里。
context 新增：≈1000-5000 token（取决于技能长度）
按技能执行：Agent 照着全文工作
技能全文在 context 里了，Agent 按里面的步骤执行。其他 99 个没被触发的技能仍然只有元数据在 context 里，不浪费空间。
执行完毕后，技能全文留在 context 直到会话结束
4
图解：100 个技能装了，只有 1 个"打开"
启动时：所有技能只加载"封面"
写周报
name + desc
做 PPT
name + desc
数据分析
name + desc
写邮件
name + desc
…×96
name + desc
每个只占 20-50 token，100 个加起来才 ~3000 token
↓
你说"帮我写周报" → 触发匹配
触发后：只有被匹配的技能"翻开全文"
📖 写周报
全文加载 ~3000 token
步骤+门禁+模板+案例
做 PPT
仍然只有封面
数据分析
仍然只有封面
写邮件
仍然只有封面
…×96
仍然只有封面
只有"写周报"被打开（+3000 token），其他 99 个不动
这就是"渐进式加载"（Progressive Disclosure）的设计。技能可以装很多，但 context 成本只在你用到的时候才产生。这也是为什么 description 要写好——如果 description 不包含"周报"这个词，你说"帮我写周报"时 Agent 可能匹配不上，技能就白装了。
注意：同一次对话中触发多个技能是可以的。比如你说"分析 CSV 然后做 PPT"，Agent 会同时加载 data-analysis 和 make-pptx 两个技能的全文。但如果一次加载太多，就会挤压对话和文件内容的 context 空间——所以单个技能不要写太长（建议 200 行以内）。