Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add agents/modelstudioai/cli/maintaining-agent-docsgit clone --depth 1 https://github.com/modelstudioai/cliWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00000 | $0.01350 |
| Opus 5 | $0.00000 | $0.00675 |
| Sonnet 5 | $0.00000 | $0.00270 |
| Haiku 4.5 | $0.00000 | $0.00135 |
Grade A, and why
maintaining-agent-docs scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 131 lines — stays where its author put it; the contents beside it link to each section on GitHub.
维护本指南
这份"AI 维护指南"(AGENTS.md + docs/agents/*)本身也是项目资产,需要随项目演化。
谁来维护
两类人/agent 会触发更新:
- AI agent 完成改动后:回顾"这次改动是不是某个场景的常见漏点?清单是不是漏了什么?"
- 人(开发者)发现新场景:某次维护用不上
docs/agents/现有任何场景文档,新增一份
何时更新
任何一种情况发生,这份指南就该改:
- ✅ 完成改动后发现"清单里没说,但实际要做"的步骤 → 补到对应场景的必查清单
- ✅ AI 漏了某个文件,review 时被指出 → 补到对应场景的常见漏点
- ✅ 一类改动反复出现且不属于任何已有场景 → 新建场景
- ✅ 项目结构调整(新增
packages/xxx、移动主要目录)→ 改AGENTS.md的项目地图 - ✅ 全局原则调整(如开始支持海外 region、加新的 core/cli 边界规则)→ 改
AGENTS.md的通用约定
新增一份场景文档
何时新增 vs 扩展现有
- 已有场景 + 新清单项 → 直接加到对应
.md,不要新建 - 一类改动有自己独立的触发条件 + 不重叠的清单 → 新建
判断:如果两个场景的清单重叠 ≥ 80%,说明是同一场景;新增清单项即可。
步骤
- 在
docs/agents/下新建<scenario>.md,文件名 kebab-case 描述场景 - 用下方模板填充
- 在
AGENTS.md的"业务场景索引"表格里加一行(按场景频率从高到低排序) - 提 PR 时附 1-2 个真实改动 commit 链接,说明这个场景已经发生过
文件模板
# <场景中文标题>
## 触发条件
- 何时进入这份文档(2-4 条具体情况)
## 概念图(可选)
若场景涉及多文件协作,画一张简单的层次/数据流图
## 必查清单
### A. <分组名>
- [ ] 具体到文件路径的 action
- [ ] ...
### B. <分组名>
- [ ] ...
## 完成后自查
1-3 条可执行的验证命令
## 常见漏点
基于真实踩坑(初版可空,随实际场景生长)
命名约定
- 文件名:
<topic>-<verb>.md(command-add-remove.md、url-change.md、config-add.md) - 场景标题:3-6 字中文短语(命令增删改、URL / 渠道变更)
- 必查清单分组:用
### A. xxx### B. xxx字母编号,方便引用
跨场景引用
两份文档有共同规则时,一处定义、其他引用:
<!-- error-hint-change.md 是定义方 -->
## 不变量
### 1. core 的 hint 必须不含 cli 关切
<!-- url-change.md 是引用方 -->
- ✗ 在 core 的 hint 里写 URL(违反 [error-hint-change.md](error-hint-change.md) 不变量 1)
避免同一规则在 N 份文档里复制粘贴,改一处全跟。
修改 AGENTS.md(主入口)
AGENTS.md 修改频率应该远低于场景文件,只在三种情况变动:
| 触发 | 改的段落 |
|---|---|
| 加/删一个场景 | 业务场景索引表 |
| 项目结构变化 | 项目地图 |
| 全局原则变化 | 通用约定 |
不要把场景特定的清单往 AGENTS.md 塞 —— 它的设计目标是 AI 加载到上下文里 ~60 行就够,详细内容按需读 docs/agents/。
文档应该是什么样
Do
- 写清晰的 must / must-not / 必查,不写"建议"性语气
- 用 file path + 具体 action 的句式(
packages/cli/src/commands.ts:增加产品命令 map 条目) - 在每份场景末尾留常见漏点段,持续累积真实经验
- 在跨场景的不变量上互相引用,不复制
Don't
- ❌ 不写前置知识(假设读者会 TS / 会读代码)
- ❌ 不堆砌实现细节(代码改了文档也要改 — 不可持续;清单是"做什么",代码是"怎么做",后者交给代码)
- ❌ 不重复
README.md的内容(README 面向用户,本指南面向维护者) - ❌ 不写反向索引(文件 → 场景)— 双向维护成本高,AI 不需要
- ❌ 不要在场景文件里塞通用约定 — 通用的放 AGENTS.md
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- yesterday First seen · 131 lines · 0 tokens per session scan A 0d8323915e35
maintaining-agent-docs is an agent published in the GitHub repository modelstudioai/cli (320 stars, last pushed 4d ago), licensed Apache-2.0. It costs nothing until one of its globs matches a file; then it loads 1,350 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other agents, from other repositories
index
Browse built-in Agent Framework capabilities for multimodal input, tools, retrieval, evaluation, security, and autonomous execution.
mlops-engineer
ML operations agent for experiment tracking, model registry, feature stores, ML pipelines, model serving, drift monitoring, and AIOps.
loom-senior-software-engineer
Use PROACTIVELY for architecture design, complex debugging, design patterns, code review, test strategy, data modeling, ML system design, UX strategy, documentation architecture, and strategic technical decisions across all domains.
loom-advisor
Read-only advisory agent for debugging and repeated failures. Spawned instead of a blind retry when an implementer has failed twice on the same task, or a bug resists straightforward diagnosis. Returns a root-cause diagnosis plus one concrete next step.
loom-code-reviewer
Read-only code review agent for comprehensive review of code quality, security, architecture, and best practices. Cannot modify files.
integrity-check
Detect adversarial content in .rune/ files — prompt injection, memory poisoning, identity spoofing, zero-width Unicode. Verdict: CLEAN/SUSPICIOUS/TAINTED.