压缩到500行

压缩到 500 行：把「深度」请出正文，按需再叫它

本条目是「Skill Engineering」的第 7 部分，对应学习清单条目 4.3.2。

前置依赖：写第一个SKILL

为以下铺垫：CLAUDE.md与AGENTS.md分工、Gotchas章节优先

---

一、核心观点

SKILL.md 正文控制在数百行以内（业界常用 500 行作经验上限），把深度内容搬进 references/，按需加载。 上下文窗口是 Agent 的「办公桌」——桌上堆越多，越找不到重点。

你给实习生发手册，会把他这辈子可能用到的所有 SOP 全打印塞他工位吗？不会。你给一本薄的「常用操作」，附录放柜子里，需要时再翻。SKILL.md 就是那本薄手册：核心是触发后能立刻用上的；长篇示例、完整规范、工具详解，统统请进 references/，Agent 真遇到对应场景才去读。

---

二、定义 / 原理 / 实践 / 示例 / 优劣势

2.1 定义

压缩到 500 行 = 把 SKILL.md 正文收敛到「核心指令」，深度材料外置到 references/，遵循渐进式披露（progressive disclosure）。

2.2 原理：上下文成本

flowchart LR

    subgraph 胖SKILL["❌ 胖 SKILL.md（600+ 行）"]

      A1[全部内容一次性进上下文] --> A2[占用数千 token / 遵循率下降]

    end

    subgraph 瘦SKILL["✅ 瘦 SKILL.md（≤500 行）+ references/"]

      B1[只加载核心] --> B2[触发时才 Read 深度文件]

      B2 --> B3[上下文省，遵循率高]

    end

• 官方额度：Anthropic 文档给出 Skill 三层加载的 token 成本——Level 1 元数据每次启动约 100 token/个；Level 2 正文「5k token 以内」；Level 3 资源「实质无限」（docs.anthropic.com）。500 行 ≈ 几 k token，正是 Level 2 上限的实操翻译。

• 窗口会满：Anthropic 在最佳实践里强调「上下文窗口填满后性能下降」，堆料越多越拖慢、越易错（anthropic.com/engineering/claude-code-best-practices）。

2.3 实践：识别与迁移

• 留在 SKILL.md：适用场景、核心操作步骤、Gotchas、安全边界。

• 搬进 references/：详细示例 → references/examples.md；完整规范 → references/conventions.md；工具详解 → references/tools.md。

• 引用方式：正文写「详细步骤见 references/steps.md」，Agent 按需 Read。

2.4 示例：目录结构

 
my-skill/
 
├── SKILL.md          # 核心（≤500 行）
 
├── references/       # 深度内容，按需加载
 
│   ├── examples.md
 
│   ├── conventions.md
 
│   └── tools.md
 
└── scripts/          # 可执行脚本
 
    ├── check.py
 
    └── fix.sh
 

2.5 优劣势

• ✅ 上下文占用低、遵循率高、维护易（核心与深度分离）

• ❌ 需要想清楚「什么算核心」；过度拆分也会增加跳转成本

---

三、最新研究与企业数据（2025–2026）

• 三层 token 成本（一手）：Level 1 元数据约 100 token/个 Skill；Level 2 正文 <5k token；Level 3 资源实质无限（docs.anthropic.com）。

• 上下文预算原则（一手）：Claude Code 最佳实践明确「上下文窗口填满后性能下降」，给出 Keep CLAUDE.md lean 等建议（anthropic.com/engineering/claude-code-best-practices）。

• 注：「500 行」为社区常用经验上限，非 Anthropic 硬性规定；其依据是官方「Level 2 <5k token」额度，按中文排版约合数百行。

---

四、学习资源

• 一手：Anthropic Agent Skills 文档 · Claude Code Best Practices

• 进阶：多文件架构（references/ 与 scripts/ 的完整三层）

---

五、相关链接

• 系列内：写第一个SKILL · 多文件架构 · Gotchas章节优先

• 跨系列：Harness Engineering

• 系列清单：Agent 方法论与产品思维学习路线图

---

六、核心要点

• 🎯 SKILL.md 正文压到数百行（经验上限 ~500 行），深度内容搬进 references/。

• 💡 依据：官方 Level 2 正文 <5k token、Level 3 资源无限；上下文满则性能降。

• ⚠️ 留核心（场景/步骤/Gotchas/安全），搬深度（示例/规范/工具详解）。

---

参考来源（一手链接 · 可溯源深挖）

• Anthropic Agent Skills 文档（Level 1 ~100 token；Level 2 <5k token；Level 3 无限）：docs.anthropic.com/en/docs/agents-and-tools/agent-skills

• Anthropic《Claude Code Best Practices》（上下文填满性能下降；Keep CLAUDE.md lean）：anthropic.com/engineering/claude-code-best-practices

速记卡（面试闪卡）

Q1：一句话讲清「压缩到 500 行：把「深度」请出正文，按需再叫它」到底是什么？

A：压缩到 500 行：SKILL.md 只留核心，深度搬进 references 按需读。

Q2：一、核心观点 —— 怎么理解？

A：像给实习生发手册，不会把他这辈子用到的 SOP 全塞工位，而是给本薄的”常用操作”、附录锁柜子。SKILL.md 就是那本薄手册：核心触发即用，长篇示例/规范/工具详解请进 references/，遇到才翻。这叫 Progressive Disclosure（渐进式披露）。

Q3：二、原理：上下文成本 —— 怎么理解？

A：上下文窗口是 Agent 的”办公桌”，堆越多越找不到重点。Anthropic 的三层额度：Level 1 元数据~100 token/个，Level 2 正文<5k token，Level 3 资源实质无限。500 行≈几 k token，正卡在 Level 2 上限。窗口填满性能就掉。

Q4：二、实践：识别与迁移 —— 怎么理解？

A：留 SKILL.md 的：适用场景、核心步骤、Gotchas、安全边界；搬 references/ 的：详细示例→examples.md、完整规范→conventions.md、工具详解→tools.md。正文写”详见 references/steps.md”，Agent 按需 Read。别把深度当正文喂。

Q5：二、优劣势 —— 怎么理解？

A：优点：上下文省、遵循率高、核心与深度分离好维护。缺点：得想清”什么算核心”，过度拆分反而增加跳转成本。一句话：SKILL.md 当名片，references/ 当档案柜。

Q6：核心速记主线有哪些？

• SKILL.md 压到 ~500 行（Level 2 上限）

• 深度内容搬进 references/ 按需加载

• 留核心：场景/步骤/Gotchas/安全

• 过度拆分会增加跳转成本

口诀

A：SKILL 压到五百行，

深度请进 references；

办公桌净找重点，

Level 二层莫撑爆。

相关链接

• 写第一个SKILL.md

• Gotchas章节优先

• Skill版本管理

• Gotchas优先

• 多文件架构