在 AI 编码代理的工程实践中，一个核心挑战始终存在：如何在有限的上下文窗口内，向代理提供足够准确且可操作的领域知识？Vercel 团队最近发布的实验结果为此提供了极具参考价值的量化数据：在针对 Next.js 16 API 的评估中，通过压缩的 8KB 文档索引直接嵌入 AGENTS.md 达到了 100% 的通过率，而采用技能（Skills）标准且附带显式指令的最佳配置仅能达到 79%。这一 47 个百分点的差距，揭示了当前代理技能压缩与评估体系中的关键设计取舍。
技能调用的可靠性困境
技能作为封装领域知识的开放标准，其设计初衷是让代理在需要时按需调用包含提示、工具和文档的技能包。理论上，代理应能识别何时需要框架特定的帮助，主动触发技能并获取相关文档。然而 Vercel 的评估数据表明，在 56% 的评估案例中技能从未被触发，添加技能后相较于基线没有任何提升。更令人担忧的是，在部分指标上技能甚至表现更差，例如测试环节的 58% 对比基线的 63%，这暗示未被使用的技能可能在环境中引入噪声或干扰。
这一现象并非 Vercel 独有。OpenAI 在技能评估实践中明确指出，代理不能可靠地使用可用工具是当前模型的已知局限性。当技能未被触发时，其包含的文档知识对代理而言形同虚设，所谓的按需加载优势便无从谈起。
显式指令的脆弱性
针对技能触发率低的问题，一种直观的解决方案是在 AGENTS.md 中添加显式指令要求代理优先使用技能。例如「在编写代码之前，首先探索项目结构，然后调用 nextjs-doc 技能获取文档」的指令将触发率提升至 95% 以上，通过率提升至 79%。然而 Vercel 进一步发现，指令的措辞方式会显著影响代理行为。
「你必须调用技能」的表述导致代理首先阅读文档并锚定于文档模式，反而忽略了项目上下文；而「先探索项目再调用技能」的表述则让代理先建立心智模型，再将文档作为参考，最终在需要同时修改 page.tsx 和 next.config.ts 的测试用例中表现更优。同样的技能、相同的文档，不同措辞产生了截然不同的结果，这表明依赖显式指令驱动的技能调用模式在生产环境中具有较高的脆弱性。
压缩策略与上下文预算
从技能转向 AGENTS.md 嵌入文档索引的方案，其核心优势在于消除了调用决策点。代理不再需要判断「是否应该查找文档」，因为文档索引已存在于每次对话的上下文中。但这种方案面临的核心工程挑战是上下文膨胀：一个完整的 Next.js 文档索引可能达到 40KB，远超代理单次请求的上下文预算。
Vercel 采用的解决方案是管道分隔的压缩格式，将 40KB 的原始内容压缩至 8KB，实现 80% 的空间节约。压缩后的索引采用目录路径与文档文件的映射结构，代理能够定位具体文档但无需将全部内容加载至上下文。这一设计的工程启示在于：对于代理而言，文档的位置索引与可检索性比完整内容更为重要。代理可以在需要时读取相关文件，而非在每次请求时加载全部文档。
关于上下文预算，业界逐渐形成了一套经验法则。前沿推理型 LLM 能够合理遵循约 150 至 200 条指令，而较小规模的模型注意力范围更窄，非推理型模型的指令承载能力更低。这意味着 AGENTS.md 中的每一条指令都会消耗代理的认知资源，文件中与当前任务无关的内容不仅浪费 token，还可能分散代理注意力导致性能下降。
评估指标的四维框架
OpenAI 在技能评估实践中提出的四维评估框架为生产级代理技能压缩提供了可量化的衡量标准。第一维度是结果目标，评估任务是否完成、应用程序是否正常运行。第二维度是过程目标，检查代理是否按预期调用技能并遵循预设的工具和步骤。第三维度是风格目标，验证输出是否符合预设的编码规范和项目约定。第四维度是效率目标，评估代理是否在合理范围内完成工作，避免不必要的命令调用或 token 消耗。
在实际评估中，Vercel 采用的评估套件聚焦于 Next.js 16 中尚未纳入模型训练数据的新 API，包括 connection ()、'use cache' 指令、cacheLife () 和 cacheTag ()、forbidden () 和 unauthorized ()、proxy.ts 异步 API、cookies () 和 headers () 的异步版本，以及 after ()、updateTag () 和 refresh () 等方法。这一选择标准本身就具有重要的工程意义：评估应当针对模型训练数据之外的知识点，因为在这些场景下文档访问的价值才真正得以体现。
渐进式披露的设计原则
基于上述实验数据与评估框架，生产级代理技能压缩可归纳为以下工程参数与实践建议。
在压缩策略上，文档索引应采用最小化表示，优先存储位置映射而非完整内容，8KB 级别的压缩目标可作为 Next.js 等主流框架的参考基准。在指令设计上，应遵循渐进式披露原则，AGENTS.md 中仅保留项目描述、包管理器、非标准构建命令等普适性内容，详细规则移至独立文档并在需要时按需加载。在评估覆盖上，应建立针对训练数据外 API 的专项测试集，每个技能的评估提示集可从 10 至 20 个精选案例起步，逐步扩展以覆盖真实使用中的失败场景。
技能与 AGENTS.md 并非互斥，而是服务于不同场景的互补方案。技能更适合垂直的、特定动作的工作流，如版本升级、框架迁移或应用最佳实践检查；而 AGENTS.md 嵌入索引则为所有 Next.js 任务提供横向的、普遍的知识访问能力。Vercel 的实验表明，对于通用框架知识，被动的上下文呈现目前优于主动的技能检索。
这一结论的深层含义在于：代理技能压缩的核心目标是将代理从预训练知识驱动转变为检索知识驱动，而实现这一转变的最可靠方式是在每次交互中提供稳定、可压缩且可按需扩展的文档访问路径。
资料来源：Vercel AGENTS.md 实验报告、OpenAI 技能评估指南。