用途
agent-docs 是一份参考规范，用于编写和测试任何会被智能体读取的文档：技能（skill）、AGENTS.md / CLAUDE.md、记忆页面，或通过上下文指针被引用的文档。其核心主张是：包装形式不同，但写作方法一致——目标是让智能体每次运行都走同一套过程，而非产出完全相同的输出。
主要能力
- 上下文指针：指针是保留在智能体上下文中的引用，指向上下文之外的某份材料，并编码触达条件。指针的措辞（而非目标本身）决定智能体何时、以多高可靠性去读取材料。指针需说明材料是什么，并列出应触发读取的分支；每个分支一个触发词，合并同义重复，前置关键词，删除正文已承载的身份信息。
- 两类负载：上下文负载是常驻上下文的材料（AGENTS.md 一行、技能描述等）对窗口的持续消耗；认知负载是人对“有哪些文档、何时用哪份”的记忆成本。通过指针触达的材料可避开上下文负载，代价是指针本身那一行；完全没有指针的材料则完全依赖认知负载。
- 信息层级：文档由两类内容构成——步骤（按序执行的动作）与参考（按需查阅的定义、规则、事实）。层级从高到低为：文件内步骤（主要层级）、文件内参考（按需查阅，可为平级规则集）、披露参考（推入单独文件、经指针触达，可延伸到完全外部参考）。
- 渐进披露与就地聚合：渐进披露是把材料沿层级下移以保持顶部可读，其判定测试是分支——每个分支都需要的内联，只有部分分支才触达的放到指针后。就地聚合决定同一文件内什么内容相邻放置，应把概念的定义、规则、注意事项放在同一标题下。披露文件只应有一层链接，超过约 100 行应加简短目录。
- 步骤与完成判据：每个步骤都要有完成判据，即判断工作已完成的条件。两个属性构成杠杆：清晰性（智能体能否区分完成与未完成）与要求强度（如“每个修改过的模型都已说明”比“产出变更清单”要求更高）。最强判据既可核查又具穷尽性。
- 自由度匹配：开放型工作（评审、设计）给出目标与启发式；模式型工作（报告、提交信息）给出模板或一个具体输入/输出示例；脆弱型工作（迁移、破坏性命令）给出精确命令并说明原样执行。输出模板需标明是“精确”还是“默认”。
- 拆分时机：按序列拆分（把完成后的后续步骤移出视野，减少当前步骤的抢跑），按调用拆分（技能特有）。拆分要消耗两类负载之一，只在值得时进行。
- 引导词：引导词是模型预训练中已存在的紧凑概念，以单个词反复出现而非句子，累积分布式定义，锚定一片行为区域。自造词需付出定义成本，优先使用已有词。同时应警惕否定式表述：用禁止来引导会把被禁行为拉入上下文，应改为正面陈述目标行为。规则要给出理由，以便智能体处理规则未预见的情况。
- 脚本：确定性步骤应附带脚本让智能体运行，需说明是“运行”还是“阅读”，脚本应自行处理错误、常数需注释说明、注明依赖、批量或破坏性变更采用“计划—校验—执行”流程、路径用正斜杠、MCP 工具用完整 Server:tool 名。
- 修剪：保持单一事实来源；环境本身也是事实来源，文档复述环境即缓存，只在查找代价高昂时保留；逐行检查相关性，警惕沉积；逐句排查无操作句（不改变相对默认行为的指令），失败时删除整句而非修剪词语。
- 技能机制：frontmatter 中 name 至多 64 字符、仅小写字母数字与连字符、不得含“anthropic”或“claude”、与文件夹名一致；description 至多 1,024 字符（j-skills 约定中 Copilot 限制更严），不含 XML 标签或尖括号，用第三人称，说明做什么与何时触达；SKILL.md 正文 500 行以内。调用方式分模型调用（保留描述、可被智能体自主触发与其他技能调用，付出常驻上下文负载）与用户调用（设置 disable-model-invocation: true，描述面向人，零上下文负载但依赖人记忆）。两个用户调用技能共用的参考需放到技能系统之外的普通文件。
使用方式
资料未提供具体安装命令或操作步骤，暂未提供。从内容看，这是一份供人阅读并据以编写、修改、测试智能体文档的参考规范。
适用场景
创建或编辑技能、AGENTS.md / CLAUDE.md、记忆页面、被指针引用的文档；需要控制智能体上下文成本、提高指令可预测性、设计完成判据与拆分结构时。
限制
资料为写作方法规范，未提供工具形态、平台支持、收费或效果保证；具体安装与使用命令暂未提供。