SuperAPI AI 工具集

writing-for-agents

写作与研究

查看项目

更新于 10-28 16:12

技能介绍

用途 writing-for-agents 是编写任何供智能体消费的文档的参考,包括技能(skill)、AGENTS.md、CLAUDE.md,以及通过指针被访问到的文档。它的核心观点是:这些文档的打包方式不同,但写作方式相同;相同的写作杠杆让每一份文档都变得可预测,因为智能体每次运行走的是同一套过程,而不是产出同样的输出。当所写的文档是技能时,需另外阅读 SKILL-MECHANICS.md 了解 frontmatter、调用方式选择和路由技能。

上下文指针 上下文指针是保存在智能体上下文中的一处引用,它指向某些上下文之外的材料,并编码了访问该材料的条件。技能描述是一个指针,AGENTS.md 中提到某文档的一行也是同一对象。决定智能体何时、以多可靠的程度访问材料的,是指针的措辞而非其目标。必备目标若配上措辞薄弱的指针,就是一处方差缺陷:先锐化措辞,锐化失败才考虑把材料内联。

指针承担两项任务:说明材料是什么,并列出应触发访问的分支(分支即文档处理的不同情形,不同运行会走不同路径)。始终加载的指针每个字都在每一轮消耗成本,因此比正文更需要严格精简:把引导词前置;每个分支只留一个触发条件,同义改写同一分支的词语合并;删除正文已经承载的身份信息。

两种负载 每新增一份文档或指针,都会花掉两种预算之一:上下文负载是始终加载的材料对智能体窗口的占用成本,每轮都消耗 token 与注意力,无论是否触发;认知负载是加在人的身上的成本,即存在哪些文档、何时取用哪一份——人是索引,这不是要最小化的成本,而是人类能动性的代价,应花在人类判断重要的地方。只能通过指针访问的材料免于上下文负载,代价是指针自身那一行;完全没有指针的材料则完全依赖认知负载。

信息层级 文档由两类内容构成:步骤(智能体按序执行的动作)与参考(按需查阅的定义、规则、事实)。二者可自由混合。核心决策是每块内容在信息层级中的位置,该层级按智能体需要的紧迫程度排序:文件内步骤是主层级,即智能体按序执行的内容;文件内参考按需查阅,常为扁平的同类规则集合,这是合理安排而非缺陷;披露式参考被推入单独文件,通过上下文指针访问,仅在指针触发时加载,可跨同文件夹的兄弟文件直至完全外部参考。推得太少则顶部臃肿,推得太多则隐藏了智能体真正需要的材料,这一张力就是全部决策所在。渐进式披露是沿层级向下移动,使顶部保持清晰,它主要不是 token 优化,而是保护层级的方式。分支是最干净的披露检验:每个分支都需要的内联,只有部分分支访问的推到指针之后。

同置是文件内的配套原则:层级决定一块内容放多深,同置决定它旁边放什么。把概念的定义、规则和注意事项放在同一标题下而非分散各处,读一部分就能带出相邻内容;检验标准是文档应读起来像为智能体写的文档。分散的失败模式是铺张:文档过长,即使每行都有效且唯一,注意力也会被稀释。

步骤与完成判据 每个步骤都以完成判据收尾,即告诉智能体工作已完成的条​​件。两个属性使其成为杠杆:清晰性,智能体能否分辨完成与未完成,模糊边界(如“达成理解”)会诱发提前完成;需求度,即要求多少,“每个被修改的模型都已说明”比“产出一份变更清单”更能强制深入工作,需求度不限于步骤,“每条规则都已应用”同样约束一组扁平参考。最强判据既可核查又穷尽。

何时拆分 把一份文档拆成两份会花掉两种负载之一,因此只有切分值得时才拆:按序列拆分,当后续步骤会诱使智能体急于完成当前步骤时,把后续步骤移出视野能促使更多功课;反之合并序列会让每一步的后续步骤暴露,诱发提前完成。按调用拆分属技能特有事项,见 SKILL-MECHANICS.md。

引导词 引导词是模型预训练中已存在的紧凑概念,智能体在执行文档时用它思考(如 lesson、fog of war、tracer bullets)。作为 token 重复出现而非句子,它积累分布式定义,以最少 token 锚定一整片行为,方法是调用模型已有的先验。自造词若定义清晰也可行,但自造词不调用先验,定义所耗 token 正是预训练词免费给出的部分,应优先选用已有词。它在两处锚定:正文中锚定执行,平坦参考中聚焦注意力到某类事物;指针中锚定调用,当同一词出现在提示词、文档和代码库中时,智能体把这种共享语言与材料联系起来,访问更可靠。否定是这一杠杆旁的失败模式:以禁止来引导会把被禁行为拖入上下文,使其更易获得;应改为提示正面目标(“写单行注释”),禁令只有作为无法正面表述的硬性护栏时才保留,且需与正面目标配对。

精简 每种含义只保留一个权威来源,使行为变更是单点编辑;重复既增加维护与 token 成本,又把该含义在层级中的显著度抬高到超出真实层级。环境本身也是事实来源(package.json 脚本、配置文件、目录结构、--help 输出),复述环境的文档是一份缓存,只有在查询昂贵时才值得加载;缓存智能体看不到的内容,如未写下的惯例、选择背后的理由、配置不会明说的坑。逐行检查相关性,文档越短越容易保持相关;缺少精简纪律的默认结局是沉积,陈旧层次层层堆积,因为添加感觉安全而删除感觉有风险。逐句排查无效句:模型默认已遵守的指令付出负载却什么也没说;检验标准是行为相对默认是否改变,这属于模型相对而非读者相对,分歧应通过运行文档解决而非争论。删除时删掉整句而非修剪字数;该检验同样用于评判引导词,太弱而压不过默认的词就是无效句,解药是更强的词(如 relentless)而非换一种技术。编辑完成的标准:每条规则只有一个可发现来源,分支指针精确,完成条件可核查,且没有不改变智能体行为的指令。

限制 现有资料为写作方法论参考,未说明具体的安装命令、平台支持、收费方式或量化效果;上述内容暂未提供。