为 AI Agent 优化的文档架构标准

为AI Agent优化的文档编写技能，基于Vercel基准测试设计三层上下文架构，实现100%任务通过率，解决元认知失败问题

基本信息

• 技能名称?Agent Docs
• 中文名称?为 AI Agent 优化的文档架构标准
• 作者?tylervovan
• 分类?其他
• 版本?1.0.0
• 标签?ai-agents, documentation, rag, context-optimization, llms-txt, token-efficiency

使用方法

使用说明
核心用法
agent-docs 是一套针对 AI Agent 消费场景设计的文档编写规范，主要用于创建 SKILL.md、README、API 文档等将被 LLM 在上下文窗口中读取的内容。其核心框架是 三层混合上下文架构（Hybrid Context Hierarchy） ：

1. Constitution 层（内联） ：2000-4000 token，始终驻留上下文，包含安全规则、架构约束、关键命令和文档索引
2. Reference Library 层（本地检索） ：1K-5K token 分块，按需获取的框架指南和 API 模式
3. Research Assistant 层（外部） ：需白名单授权，仅用于边缘场景如最新库更新
   显著优点
   效能验证 ：Vercel 2026 基准显示，纯工具检索通过率 53%，检索+提示 79%， 内联 AGENTS.md 达 100%
   解决根本问题 ：绕过 Agent 的"元认知失败"——Agent 不知道自己不知道什么，内联文档彻底规避此问题
   Token 效率 ：8KB 压缩索引优于 40KB 完整文档，通过文件路径、函数签名、负向约束实现高效压缩
   结构优化 ：针对 RAG 分块设计，每个 H2 区块自包含；利用 U 型注意力，关键规则置顶
   潜在局限
   维护成本 ：Constitution 层需与代码库同步更新，否则产生漂移
   规模瓶颈 ：4K token 上限限制复杂项目的规则覆盖
   外部依赖风险 ：llms.txt 等标准尚未完全统一，跨生态兼容性存疑
   适合人群
   构建 AI 原生开发工作流的团队
   维护大型代码库、需多 Agent 协作的工程师
   追求极致上下文效率的技术作者
   常规风险
   安全边界 ：内联内容可信，但外部检索存在提示注入和 SSRF 风险
   过度压缩 ：关键信息遗漏可能导致 Agent 误判
   格式僵化 ：机械追求 SNR 可能降低人类可读性