Agent Skill 原理与工程实践（二十）：如何控制 Skill 上下文大小 前面几章已经完成了 Skill 的工作流、工具调用、控制流和组合设计。从本章开始进入第六阶段：Context Engineering。
大纲给出的上下文加载链路是：
1 2 3 4 5 6 7 Skill Metadata
这四层不是普通的目录分类，而是一套上下文预算策略：
Metadata 只负责让模型发现 Skill；
Core Workflow 只负责让模型正确执行主流程；
Conditional References 只在特定分支需要时读取；
Tool Results 只保留完成当前决策所必需的信息。
控制上下文大小的目标并不是单纯“少用 token”，而是提高有效信息密度，让模型在正确的时刻看到正确的信息。
1. 上下文窗口不是资料仓库 Skill 目录可以保存大量资料，但模型当前上下文不应该装下全部资料。
应把两个概念分开：
1 2 3 4 5 Available Knowledge
理想状态是：
1 2 Available Knowledge 很大
如果把所有可用知识都预先放入上下文，就会出现：
与当前任务无关的信息争夺注意力；
关键约束被长文淹没；
输入成本和延迟增加；
更早触发 compaction 或截断；
相似规则发生冲突；
工具结果不断累积，后续决策越来越不稳定。
所以，Context Engineering 的本质是选择、组织、加载、压缩和淘汰信息 。
2. “上下文越多，效果越好”为什么是错的 大上下文窗口只表示模型最多能接收多少内容，不表示每一段内容都能带来正收益。
可以用一个简单概念表达：
1 2 3 4 5 6 Context Utility
同一份资料在不同阶段，价值并不相同：
信息
Triage 阶段
深度分析阶段
报告阶段
用户目标
高
高
高
完整 trace 原文
低
中
低
领域规则
低
高
低
已验证 finding
中
高
高
报告模板
低
低
高
因此，上下文管理不能只设一个总 token 上限，还要按阶段决定哪些信息应该出现。
3. 四层上下文模型 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ┌──────────────────────────────────────┐
越靠上，越早加载、越常驻，因此必须越短、越稳定；越靠下，越贴近当前任务，可以更具体，但要严格按需读取和及时释放。
Metadata 的任务是帮助模型回答：
1 2 这个 Skill 是做什么的？
例如：
1 2 3 4 --- name: scheduler-analysis description: Analyze scheduler traces for run-queue latency, wakeup delay, CPU contention, migration, and affinity issues. Use after triage identifies scheduler signals or when the user explicitly requests scheduler analysis. ---
它不应该包含：
完整执行步骤；
大段领域知识；
所有输入输出示例；
工具 API 说明；
故障排查手册；
历史变更记录。
OpenAI 官方资料指出，每个 Skill 的 name 和 description 都会进入模型上下文；当 Skill 太多、description 太长时，系统可能需要缩短描述，模型反而更难选择正确能力。
因此 Metadata 要追求：
1 2 Specific enough to route
假设安装 50 个 Skill，每个 description 都写 300～500 个英文词，即使任何 Skill 尚未执行，发现层就已经很重。
控制方式包括：
只挂载当前角色需要的 Skill；
description 用一两句说明能力与触发时机；
删除营销式介绍和重复关键词；
避免每个 Skill 都声称“必须在任何相关任务中使用”；
对大型 Skill 集先做路由，再暴露子集合。
5. 第二层：Core Workflow 只保留执行主干 Skill 触发后，模型需要知道怎样正确执行。这部分放在 SKILL.md 主体中。
Core Workflow 应包含：
角色和职责边界；
必要输入与前置条件；
主流程步骤；
关键分支入口；
必须遵守的安全约束；
输出契约；
最终检查；
去哪里读取条件资料。
不应默认包含：
每个工具的完整手册；
所有领域背景知识；
大量相似示例；
很少使用的异常分支细节；
可由脚本执行的算法实现；
整份 Schema 或数据字典。
5.1 根 SKILL.md 应像路由器 OpenAI 官方建议，对于包含多个工作流的 Skill，让根文档成为最小路由器：给模型足够信息判断下一步去哪里，但不要迫使它读取当前任务不需要的内容。
例如：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 # Scheduler Analysis ## Workflow 1. Validate the trace type and requested time range.2. Select one analysis path: - Run-queue latency → read `references/runqueue.md` - Wakeup delay → read `references/wakeup.md` - CPU affinity → read `references/affinity.md` 3. Run the referenced analysis script.4. Validate the output against `schemas/scheduler-finding.json` .5. Return evidence, counter-evidence, confidence, and unknowns.## Boundaries - Do not diagnose memory or storage causes.- Emit cross-domain signals instead.
如果用户只调查 wakeup latency，模型无需加载 runqueue 和 affinity 的详细规则。
6. 第三层：Conditional References 按条件加载知识 条件引用解决的是：
适合拆入 reference 的内容包括：
特定子领域的判断规则；
大型 API 或命令参考；
数据字典和 Schema；
平台差异；
罕见故障处理；
详细示例；
术语表；
历史兼容信息。
6.1 条件必须写得可执行 不推荐：
1 必要时参考 `references/advanced.md` 。
“必要时”没有可操作标准。
推荐：
1 2 3 - If `trace_format == perf-script` , read `references/perf-script.md` .- If the finding involves CPU affinity or migration, read `references/affinity.md` .- If the output fails schema validation, read `references/output-repair.md` once.
这相当于为 reference 建立加载谓词：
1 load(reference) only if condition == true
6.2 引用保持浅层 不推荐：
1 2 3 4 5 SKILL.md
深层引用会让模型遗漏关键文件，也增加导航成本。
推荐：
1 2 3 4 5 SKILL.md
根文件直接指向任务分支所需资料，尽量只跨一层。
6.3 大型 Reference 需要目录与定位提示 如果一个 reference 无法继续合理拆分，应提供：
目录；
稳定标题；
搜索关键词；
适用条件；
明确的不适用范围。
例如：
1 2 3 4 Read only the section matching the detected kernel family:- Linux 5.x → `## Linux 5.x event mapping` - Linux 6.x → `## Linux 6.x event mapping`
工具返回的是动态事实，也是 Agent 循环中增长最快的内容。
典型膨胀来源包括：
搜索返回完整网页；
shell 输出数万行日志；
API 返回整个对象树；
解析器重复返回原始数据；
每次重试都保留几乎相同的错误；
子 Agent 把完整推理历史传回主 Agent。
工具输出的正确原则不是“越完整越好”，而是：
1 2 3 Raw data stays outside context.
7.1 原始数据、工件和摘要分离 1 2 3 4 5 6 7 Raw trace
模型通常只需要：
工件标识；
查询范围；
关键统计；
异常片段；
证据位置；
截断说明。
而不是完整原始文件。
不推荐接口：
推荐接口：
1 2 3 4 5 6 7 search_logs(
工具应让调用者控制：
时间范围；
字段选择；
结果数量；
排序；
去重；
分页游标；
是否包含原文片段。
7.3 输出摘要必须保留可追溯性 1 2 3 4 5 6 7 8 9 10 11 12 { "summary" : "14:03-14:04 runqueue latency sharply increased" , "evidence_count" : 28 , "top_examples" : [ "event-188" , "event-201" ] , "artifact_ref" : "artifact://sched/events.json" , "query" : { "from" : "14:03:00" , "to" : "14:04:30" } , "truncated" : true , "next_cursor" : "cursor-2" }
摘要不能变成无来源的结论；模型应能按需回查原始证据。
8. Context Budget：给每一层设预算 不要只依赖模型的最大 context window。应在 Skill 设计中定义软预算：
1 2 3 4 5 6 7 context_budget: metadata_tokens: 120 core_workflow_tokens: 2500 conditional_reference_tokens: 6000 active_tool_result_tokens: 8000 reserved_for_user_and_system: 4000 reserved_for_output: 3000
这里的数字只是示例，真实预算应通过 Eval 调整。重点是显式区分：
1 2 3 4 固定成本
如果不预留输出空间，输入阶段即使没有超限，最终回答也可能被迫缩短或截断。
9. Context Ledger：知道 token 花在了哪里 一次 Skill 执行可以维护上下文账本：
1 2 3 4 5 6 7 8 9 10 11 12 context_ledger: system_and_project_rules: 1800 skill_metadata: 950 active_skill_workflow: 2100 references: wakeup.md: 1700 conversation_history: 3200 tool_results: trace_summary: 2600 metrics_query: 900 working_state: 700 total_input_estimate: 13950
账本的作用不是追求绝对精确，而是发现主要增长点：
Metadata 是否因 Skill 太多而膨胀；
SKILL.md 是否承担了百科全书职责；某个 reference 是否每次都被无条件读取；
Tool 是否重复返回大量相同内容；
历史会话是否应该压缩或新开任务。
10. 上下文生命周期：进入、保留、压缩、淘汰 每一类信息都应有生命周期：
1 Discover → Load → Use → Distill → Evict
10.1 Discover 只暴露 Metadata 或索引，让模型知道信息存在。
10.2 Load 满足明确条件时读取正文或查询工具。
10.3 Use 信息参与当前判断，并产生结论或下一步动作。
10.4 Distill 把大结果转成结构化 finding、状态摘要或工件引用。
10.5 Evict 当原始信息不再影响未来决策时，从活动上下文移除。
这比“上下文满了再统一压缩”更主动，也更可控。
11. Working State 与对话历史分离 长任务不应该依赖模型从几十轮对话中重建当前状态。
可以维护结构化 Working State：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 goal: 定位 14 :00-14:10 P99 延迟异常 constraints: - read_only - no production restart confirmed_facts: - p99 increased from 120ms to 840ms - io latency correlated at 0.81 open_hypotheses: - id: H1 claim: storage saturation contributed to latency status: supported - id: H2 claim: scheduler contention is primary status: insufficient_evidence artifacts: - artifact://normalized-trace completed_steps: - triage - io-analysis next_steps: - collect missing scheduler counters
后续步骤优先读取这份状态，而不是重复加载全部聊天和工具原文。
Working State 应保存事实、决定、约束、工件和未决事项，不应保存冗长叙事。
12. Trimming 与 Summarization 如何选择 OpenAI 的上下文管理资料区分了两种常见方法。
12.1 Trimming：裁掉旧内容 优点：
行为确定；
不需要额外模型调用；
最近内容保持原样；
容易调试和复现。
风险：
早期的重要约束可能突然消失；
最近一次超大工具输出仍可能占满窗口；
长期承诺和标识可能丢失。
适合局部、短周期、工具密集且早期历史价值低的工作流。
12.2 Summarization：把旧内容压缩成状态 优点：
能保留长期目标与关键决定；
用较小体积承载较长历史；
适合研究、规划和长会话。
风险：
摘要可能遗漏或歪曲信息；
错误事实可能污染后续上下文；
需要记录摘要输入输出并单独评测。
12.3 Skill 中的推荐策略 1 2 3 4 5 Immutable constraints → 单独保留，不依赖摘要
关键约束不能仅存在于会被裁剪的历史中，也不能完全依赖非确定性摘要。
13. Prompt Caching 不是 Context Reduction 这是一个常见误区。
1 2 3 4 5 Prompt Caching
缓存后，内容通常仍属于模型输入上下文，只是重复使用更经济。它不能解决：
无关信息干扰；
指令冲突；
超过上下文上限；
Tool Result 长期堆积；
模型难以定位关键信息。
所以，应先控制加载内容，再对稳定且必要的前缀使用缓存。
Anthropic 的工具上下文文档提出：大量工具时，不必把所有 Tool Schema 预先塞入上下文，可以先暴露搜索能力，按需发现工具。
这与 Skill 的 Progressive Disclosure 本质一致：
1 2 3 4 5 6 7 8 Skill Discovery
三者遵循同一条原则：
先提供选择所需的最小信息，做出选择后再加载执行所需的详细信息。
15. 用脚本减少上下文，而不只是提高确定性 脚本除了提供稳定执行，还能避免把大量实现和中间数据放进模型上下文。
例如分析一百万行 trace：
1 2 3 4 5 错误方式：
脚本输出应面向决策：
1 2 3 4 5 6 7 8 9 10 11 { "window" : "14:03:00/14:04:00" , "runqueue_p50_ms" : 3.2 , "runqueue_p99_ms" : 47.2 , "top_tasks" : [ { "pid" : 1024 , "p99_ms" : 61.8 } ] , "anomalous_intervals" : [ { "start" : "14:03:17" , "end" : "14:03:28" } ] }
而不是把原始事件重新打印一遍。
16. 多 Skill 场景中的上下文隔离 父 Skill 不应把全部上下文广播给每个子 Skill。
1 2 3 4 5 6 Parent Context
应为子 Skill 构造 Task Packet：
1 2 3 4 5 6 7 8 9 10 11 task_id: sched-001 objective: 验证调度等待是否参与延迟异常 constraints: - read_only - incident_window_only inputs: trace_ref: artifact://normalized-trace time_range: 14 :00/14:10 known_facts: - p99 spike confirmed expected_output: scheduler_finding_v1
子 Skill 完成后，只返回结果 Envelope、必要工件引用和警告，不把自己的完整历史传回父上下文。
这样既隔离职责，也防止上下文呈乘法增长。
17. Retrieval 不是把搜索结果全部放入 Prompt 检索系统应包含三个阶段：
1 2 3 4 5 6 Candidate Retrieval
如果只做第一步，就会把大量“可能相关”资料塞进窗口。
Context Package 应包含：
当前 claim 或子问题；
精选片段；
来源标识；
时间与版本；
适用范围；
必要时的反证；
是否截断。
不要把检索排名当作事实置信度，也不要因为内容进入上下文就默认它正确。
18. 过时信息与重复信息的处理 18.1 过时信息 每条动态事实应带时间或版本：
1 2 3 4 value: 47.2 metric: runqueue_p99_ms observed_at: 2026-10-07T14:03:40+08:00 source: artifact://sched-summary
新结果到来时，不应让旧结果继续以同等权重常驻。
18.2 重复信息 同一事实可能同时出现在：
用户消息；
Tool Result；
工作摘要；
子 Skill 输出；
最终草稿。
推荐保留一个规范状态，并让其他位置引用它：
1 2 3 4 5 Canonical Fact Store
重复不仅浪费 token，还会在副本不一致时造成冲突。
19. 注意力优先级：重要内容放在哪里 精简之外，还要保证关键内容容易被找到。
推荐结构：
1 2 3 4 5 6 7 8 9 # Skill Name ## Role and boundaries ## Required inputs ## Workflow ## Conditional references ## Output contract ## Failure policy ## Final check
重要规则应：
出现在相关步骤附近；
使用一致术语；
避免在多个文件重复定义；
必要时用 MUST 或明确禁止，而不是含糊建议；
能由脚本或 Schema 验证时，不只依赖自然语言强调。
不要试图通过重复十遍来提高规则权重。重复会增加上下文，并可能出现版本不一致。
20. 一个可复用的上下文路由模板 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 ---description: Investigate cross-domain system performance incidents. Use when the responsible subsystem is unknown or findings from multiple domains must be correlated. --- # Performance Analysis ## Core workflow 1. Validate the incident objective and artifact references.2. Read `references/triage.md` only when no target domain is known.3. Select specialist analysis: - Scheduler signals → delegate to `scheduler-analysis` . - Memory signals → delegate to `memory-analysis` . - I/O signals → delegate to `io-analysis` .4. Store raw outputs as artifacts; keep only validated findings active.5. Correlate findings and record contradictions.6. Invoke `report-generator` only after analysis is complete.## Conditional references - Kernel-version compatibility issue → read `references/kernel-compat.md` .- Conflicting findings → read `references/conflict-resolution.md` .- Schema validation failure → read `references/output-repair.md` once.## Context policy - Do not load every reference upfront.- Do not paste raw traces into the conversation.- Pass each specialist a minimal task packet.- Replace completed tool exchanges with a validated finding and artifact reference.- Preserve user constraints and unresolved questions verbatim.## Final check - Every claim has a source or is labeled as a hypothesis.- No stale tool result overrides a newer result.- Partial coverage is disclosed.
这个模板把上下文策略变成工作流的一部分，而不是运行时出问题后再补救。
21. 何时应把信息留在 SKILL.md 满足下面多数条件时，适合留在核心工作流：
几乎每次执行都需要；
遗漏会直接导致流程错误或安全问题；
内容短而稳定；
决定下一步读取哪个 reference；
是输出契约或最终检查的一部分。
例如：
1 2 3 “不要修改原始 trace”
这类规则不应藏在深层 reference 中。
22. 何时应把信息拆到 Reference 满足下面任一条件时，优先拆出：
只在少数分支使用；
内容较长；
更新频率与核心工作流不同；
属于平台、版本或领域细节；
可以通过明确条件定位；
不读取也能完成其他大多数任务。
判断公式可以写成：
1 2 Expected Context Cost
一份 5,000 token 的资料如果只有 5% 任务需要，按需加载通常比放入核心工作流合理得多。
23. 常见反模式 结果是所有会话都承担成本，且相邻 Skill 的描述互相挤压。
23.2 SKILL.md 变成知识百科 所有背景、API、示例和故障都放在正文，导致 Skill 一触发就加载整套资料。
23.3 无条件读取 references 虽然文件拆开了，但第一步要求“阅读 references 下所有文档”，等于没有渐进披露。
缺少筛选、分页、摘要和工件引用，Agent 每执行一步都使上下文变大。
23.5 摘要替代事实来源 摘要经过模型解释，不能成为唯一证据。必须保留原始工件引用和可回查路径。
23.6 把缓存当作压缩 缓存减少重复计费或处理，不会消除无关内容对注意力和窗口容量的占用。
23.7 只在超限后处理 等 context overflow 或 compaction 才开始管理，往往已经丢失了重要结构。应从 Skill 信息架构阶段设计预算。
23.8 每个子 Skill 都接收完整父上下文 会让多 Skill 组合的上下文成本快速放大，也破坏职责隔离。
24. 如何评测上下文设计 24.1 Context Cost 1 2 3 平均输入 token
24.2 Retrieval Efficiency 1 2 3 读取的 Reference 中有多少真正用于结果
1 2 3 原始输出大小 / 注入上下文大小
24.4 Quality 1 2 3 4 5 任务完成率
24.5 Context Ablation Test 逐步移除某段上下文，观察质量是否下降：
1 2 3 删除后质量不变 → 可能是冗余
这比凭感觉精简更可靠。
25. 官方资料带来的工程启示 25.1 OpenAI：Skill 根文档应成为最小路由器 官方 OpenAI Docs 强调，读取 Skill 本身会占用上下文。多工作流 Skill 应让根文档只提供选择分支所需的信息，再指向相应支持文档和脚本。
25.2 OpenAI：长会话需要裁剪或压缩，但两者风险不同 Trimming 更确定，却可能突然遗忘早期信息；Summarization 能保留长期状态，却可能产生摘要漂移和上下文污染。因此关键约束、确认事实和原始证据引用应分层保存。
25.3 Anthropic：上下文窗口是共享资源 Skill 与 system prompt、对话历史、其他 Skill metadata 和用户请求共享上下文。写入任何一段内容都应问：它是否值得长期占用注意力？
25.4 Anthropic：渐进披露是三级加载机制 Metadata 常驻，SKILL.md 在触发时读取，额外资料与脚本按需访问。这使 Skill 可以携带丰富资源，而不必让全部资源进入当前上下文。
25.5 Anthropic：Tool Context 也要按需发现和淘汰 Tool Search 减少预加载定义，Programmatic Tool Calling 减少中间往返结果，Context Editing 清理失去价值的旧结果。它们分别处理上下文膨胀的不同阶段。
26. 本章最终模型 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 ┌─────────────────────────┐
控制 Skill 上下文大小的核心不是固定某个 token 数字，而是建立加载纪律：
1 2 3 4 5 先发现，再读取；
27. Skill 专项复盘 27.1 Skill 目录很大是否一定有问题？ 不一定。未读取的 reference、asset 和 script 不占用活动上下文。问题在于是否有清晰的按需加载路径。
27.2 SKILL.md 是否越短越好？ 不是。它必须完整承载核心工作流、关键约束和路由逻辑。目标是最小充分，而不是机械追求最少字数。
当前判断所需的结构化结果应该进入；大规模原始数据应保存为工件，通过引用和按需查询访问。
27.4 有 Prompt Cache 后还需要精简吗？ 需要。缓存降低重复成本，但不能减少窗口占用、噪声或指令冲突。
27.5 如何证明上下文设计有效？ 同时测量输入 token、参考资料命中率、工具输出压缩比、任务完成率、约束遵从、摘要保真度和长任务遗忘率。
28. 本章实践 选择一个现有 Skill，完成一次 Context Audit：
统计 Metadata、核心工作流、Reference 和 Tool Result 的大小；
标记哪些信息始终需要、条件需要或只用于单步决策；
把根 SKILL.md 重构为最小工作流路由器；
为每个 reference 写出明确加载条件；
将引用深度压到一层；
为大 Tool Result 增加过滤、分页、摘要和工件引用；
建立结构化 Working State；
为关键约束设计不可丢失的保存位置；
对裁剪和摘要分别做事实保真测试；
运行 Context Ablation，删除没有质量贡献的内容。
下一章将严格按照大纲继续讨论不同指令层的职责与优先级：
第 21 章：Skill 与 AGENTS.md / System Prompt / User Prompt 的关系。
官方参考资料