Model-Optimizer Agent 工具链配置指南：共享指令、可安装 Skills 与本地覆盖机制

Model-Optimizer 不仅是一个面向 LLM 的量化、剪枝、蒸馏等模型优化统一库，其仓库还内置了一套完整的 AI Agent 工具链（.agents/目录与modelopt插件），供 Claude Code、Codex 等编码代理在仓库内协作开发、量化、评测与部署。本文基于仓库维护文档 .agents/TOOLING.md，并结合 .agents/README.md、plugins/modelopt/.claude-plugin/plugin.json 等源码配置，系统讲解这套 Agent 设置的三大支柱：共享指令（Shared Instructions）、可安装 Skills（Installable Skills）与本地覆盖（Local Overrides）。读完本文，你将掌握如何在任意工作区安装并使用 Model-Optimizer 的 Agent Skills、如何为仓库级指令与个人级覆盖分层配置，以及如何维护一个多 Agent 兼容的仓库协作环境。

一、为什么需要 Agent 工具链配置

Model-Optimizer 的日常开发与评测工作流高度依赖 AI 代理：从 PTQ 量化配方搜索（quant-recipe-search）、模型部署（deployment）、评测运行（evaluation、launching-evals），到远端集群上的 SLURM 作业监控（monitor），每一步都有对应的 Skill 文件来约束代理的行为。这些指令如果直接写死在代理的系统提示里，会带来两个问题：

• 可复用性差：换一个工作区或换一个代理工具，指令就要重新编写；
• 上下文膨胀：代理每次运行都要加载全部指令，token 成本随指令体积线性增长。

为此，Model-Optimizer 把 Agent 配置拆成三层：仓库级共享指令、可安装/可移植的 Skills、以及仅对单个开发者生效的本地覆盖。三者由 .agents/TOOLING.md 统一约定，再由 .agents/README.md 详细描述目录布局与各代理的发现机制。下面逐层展开。

二、共享指令：AGENTS.md 与 CLAUDE.md 的符号链接机制

TOOLING.md第一条约定直指指令的单一事实来源（Single Source of Truth）：

更新AGENTS.md以维护仓库级 Agent 指令；CLAUDE.md是AGENTS.md的符号链接，因此对该文件的修改会同时作用于 Codex 与 Claude Code。

也就是说，AGENTS.md是唯一需要编辑的文件，CLAUDE.md只是兼容入口。查看仓库根目录可以确认这一约定确实生效：CLAUDE.md 与 AGENTS.md 同时存在，而仓库级指令的全部内容都维护在AGENTS.md中。

从 AGENTS.md 的实际内容可以看到，这套共享指令覆盖了代理在仓库内工作的关键约束：

• 仓库定位（Repository orientation）：先读README.md了解项目与安装方式；源码在modelopt/、测试在tests/、用法示例在examples/或docs/；Agent Skills 的规范树位于plugins/modelopt/skills/，而.agents/skills与.claude/skills只是指向该规范树的相对符号链接；
• 编码规范：开发与评审前必须阅读 CONTRIBUTING.md 中的 Coding Standards，不得跳过；
• 迭代开发：测试运行遵循CONTRIBUTING.md的「Writing and Running Tests」章节，快速迭代时优先选择tests/中针对变更区域的聚焦测试；
• 提交纪律：使用git commit -s -S签名提交；未经当前轮次明确许可不得git push，发布类操作（push、gh pr create等）必须先等待用户明确指示；
• Skills 更新原则：Skill 编辑要精简，因为每行都会在每次使用时消耗代理上下文 token，只添加能改变代理行为的内容，优先压缩既有文本；开 PR 前必须做最终压缩；
• PR 规模控制：每个待评审 PR 尽量控制在约 500 行变更以内，超预算时先提议拆分（按结构拆优先于按功能拆），再用git diff --stat校验规模。

这套约定说明了「共享指令」层的设计哲学：它只承载跨工具、跨任务都成立的仓库规则，把任务相关的领域知识全部下沉到 Skills 层，从而控制上下文成本。

三、可安装 Skills：modelopt 插件与安装命令

TOOLING.md的第二条约定：

modelopt插件将仓库的 Skills 打包，供任意工作区使用；安装命令见 README.md 的 "AI Agents" 章节。

这意味着 Skills 不是只能在本仓库内使用，而是可以像 VS Code 扩展一样安装到任何工作区。README 中给出的安装命令如下：

# Claude Code claude plugin marketplace add https://github.com/NVIDIA/Model-Optimizer.git claude plugin install modelopt@modelopt # Codex codex plugin marketplace add https://github.com/NVIDIA/Model-Optimizer.git

安装完成后，在 Codex 中打开/plugins，选择modeloptmarketplace 并安装modelopt即可。对于仓库贡献者，也可以跳过插件安装，直接从本地检出（checkout）使用 Skills。

3.1 插件与 Marketplace 清单

支撑这套安装机制的配置文件有两份：

• .agents/plugins/marketplace.json —— Codex 的 marketplace 清单，声明插件名为modelopt、显示名为 "NVIDIA Model Optimizer"、来源为本地路径./plugins/modelopt，并设置installation: AVAILABLE、authentication: ON_INSTALL的安装策略；
• plugins/modelopt/.claude-plugin/plugin.json —— Claude Code 的插件清单，除名称、版本（0.1.0）、描述（涵盖 Model Optimizer 开发、量化、部署与评测的 Skills）、关键字（modelopt、quantization、evaluation、deployment、llm）与 Apache-2.0 许可证外，还内嵌了一个MCP 服务器配置：

"mcpServers": { "modelopt": { "command": "uvx", "args": [ "--from", "git+https://github.com/NVIDIA/Model-Optimizer.git#subdirectory=tools/mcp", "modelopt-mcp" ] } }

也就是说，安装modelopt插件后，代理不仅能加载本地 Skills，还能通过uvx启动仓库tools/mcp子目录下的modelopt-mcpMCP 服务器，获得额外的工具能力。

3.2 Skills 的目录组织与 SKILL.md 规范

Skills 的规范树位于 plugins/modelopt/skills/，每个 Skill 以<skill-name>/SKILL.md形式组织，并附带references/、scripts/、tests/等支撑文件。从目录树可以看到完整的技能矩阵，例如：

• common/—— 共享支撑文件（environment-setup.md、slurm-setup.md、remote-execution.md、credentials.md、workspace-management.md等）；
• ptq/—— 后训练量化，含checkpoint-validation.md、launcher-guide.md、slurm-setup-ptq.md、unsupported-models.md等参考；
• qad/、speculative-decoding/、quant-recipe-search/—— 量化感知蒸馏与投机解码相关；
• deployment/—— 部署，含references/benchmarking.md、trtllm.md、vllm.md、sglang.md、support-matrix.md与scripts/deploy.sh；
• evaluation/、launching-evals/、accessing-mlflow/、compare-results/、monitor/—— 评测与作业监控；
• debug/、day0-release/、release-cherry-pick/等 —— 调试与发布流程。

每个SKILL.md采用统一的 YAML frontmatter + Markdown 正文结构。以 plugins/modelopt/skills/deployment/SKILL.md 为例：

--- name: deployment description: Serve a quantized or unquantized LLM checkpoint as an OpenAI-compatible API endpoint using vLLM, SGLang, or TRT-LLM. Use when user says "deploy model", "serve model", ... Do NOT use for quantizing models (use ptq) or evaluating accuracy (use evaluation). license: Apache-2.0 ---

description字段会明确告诉代理何时该用、何时不该用这个 Skill（例如部署任务应使用deployment而非ptq或evaluation），这是代理在运行时正确路由到对应 Skill 的关键信号。正文则给出可直接执行的命令，如：

"$SKILL_DIR/scripts/deploy.sh" start --model ./qwen3-0.6b-fp8 "$SKILL_DIR/scripts/deploy.sh" start --model ./llama-70b-nvfp4 --framework sglang --tp 4 "$SKILL_DIR/scripts/deploy.sh" test "$SKILL_DIR/scripts/deploy.sh" status "$SKILL_DIR/scripts/deploy.sh" stop

3.3 多 Agent 的发现机制与符号链接约定

不同代理发现 Skills 的机制各不相同，.agents/README.md 的「How each agent finds these」给出了精确的兼容策略：

• Claude Code只会在.claude/skills/下自动发现 Skills，因此.claude/skills/存放指向.agents/skills/的相对符号链接；
• 仓库内代理使用.agents/skills（指向插件的相对符号链接）；
• Claude Code 与 Codex 插件直接加载plugins/modelopt/skills；
• Claude Code 子代理通过插件从plugins/modelopt/agents/加载，同时.claude/agents/*.md符号链接把子代理暴露给仓库用户（参见modelopt-model-deployer、modelopt-model-quantizer、modelopt-model-evaluator、modelopt-model-performance-benchmarker、modelopt-model-quantize-recipe-searcher等角色定义）；
• Codex直接从.codex/agents/发现项目角色，且 Codex 插件目前无法安装自定义角色。

这套「永远不复制、只做符号链接」的设计，保证了.agents/README.md中所说的编辑规则可以严格成立：所有 Skills 一律在plugins/modelopt/skills/下编辑，代理各自目录下的同名文件只是入口。Claude Code 子代理归属plugins/modelopt/agents/，Codex 自定义角色归属.codex/agents/，新 Skill 统一放到plugins/modelopt/skills/<skill-name>/SKILL.md，共享支撑文件放在plugins/modelopt/skills/common/。

3.4 上游 Skills 的同步机制

仓库中存在两类 Skill：自研 Skill 与「逐字转售（vendored verbatim）」的上游 Skill。后者由 .agents/scripts/sync-upstream-skills.sh 统一管理——该脚本以固定 SHA（默认DEFAULT_SHA）从NVIDIA-NeMo/Evaluator的packages/nemo-evaluator-launcher/.claude/skills拉取launching-evals与accessing-mlflow两个 Skill，覆盖写入.agents/skills/（兼容符号链接），并自动在SKILL.mdfrontmatter 的description:之后注入来源与许可证行（幂等操作）。

需要注意：这些逐字转售的 Skill 禁止手工修改，本地改动会在下次同步时被覆盖；而evaluationSkill 是上游nel-assistant的修改版 fork，不受该脚本管理，上游更新时需要手动同步。日常使用方式为：

.agents/scripts/sync-upstream-skills.sh # 按固定 SHA 重新同步 UPSTREAM_SHA=<sha> .agents/scripts/sync-upstream-skills.sh # 升级到新 SHA

该脚本依赖gh、base64、awk工具，且必须从仓库根目录运行。

四、本地覆盖：CLAUDE.local.md 与 AGENTS.override.md

TOOLING.md的第三条约定针对个人本地指令，并强调两种代理的覆盖语义完全不同：

对于私有本地指令，使用工具特定的覆盖文件：

• Claude Code：CLAUDE.local.md是追加式的，在CLAUDE.md之后被读取；
• Codex：AGENTS.override.md会替换同目录下的AGENTS.md，因此它不是追加式的，必须重述仍应生效的共享指令。

这是全文最容易被忽略、却最容易踩坑的一条：对 Claude Code 来说，个人习惯配置可以增量叠加；对 Codex 来说，一旦出现AGENTS.override.md，仓库级AGENTS.md就不再生效，任何仍需保留的共享约束（如签名提交、push 审批、PR 规模）都必须显式写进 override 文件，否则代理的行为约束会静默丢失。

五、配套设施：远端集群配置与 MCP 服务器

除三大支柱外，.agents/还承载两项与代理实际执行密切相关的配置：

远端集群配置。remote-execution、monitor、ptq、launching-evals等 Skill 在把任务提交到 GPU 工作站或 SLURM 集群时，会按序查找clusters.yaml：依次为~/.config/modelopt/clusters.yaml（用户级，推荐）、<repo-root>/.agents/clusters.yaml（项目级，规范位置）、<repo-root>/.claude/clusters.yaml（项目级，向后兼容）。模板见 .agents/clusters.yaml.example，其结构示例如下：

clusters: my-cluster: login_node: cluster-login.example.com user: myusername ssh_key: ~/.ssh/id_rsa workspace: /path/to/remote/workdir gpu_type: H100 # 用于量化格式推荐 # slurm: # default_account: my_account # default_partition: batch_short default_cluster: my-cluster

其中gpu_type字段会被用于量化格式推荐（例如 FP8 与 NVFP4 的选择），slurm子块则为作业调度提供默认账户与分区。

MCP 服务器。如前所述，plugins/modelopt/.claude-plugin/plugin.json 通过uvx声明了modelopt-mcp服务器（源码位于tools/mcp），安装插件后代理即可访问由该服务器提供的额外工具，例如accessing-mlflowSkill 所依赖的 MLflow 访问能力。

六、总结：一套可移植、可叠加、可维护的 Agent 配置体系

回到 .agents/TOOLING.md 的定位——它是写给「维护仓库 Agent 设置的人类」的速查笔记，而非每次加载的代理指令。它通过三条约定构建了完整的配置分层：

1. 共享指令收敛到AGENTS.md单一事实来源，CLAUDE.md符号链接保证 Claude Code 与 Codex 行为一致；
2. 可安装 Skills由modelopt插件打包，通过 marketplace/plugin 清单安装到任意工作区，SKILL.md 的 frontmatter 驱动代理按需加载，且与上游同步、仓库符号链接等机制共同保证「单一编辑点」；
3. 本地覆盖严格区分追加式（CLAUDE.local.md）与替换式（AGENTS.override.md），避免个人配置污染仓库指令，也避免替换语义导致共享约束被静默丢弃。

对于想在 Model-Optimizer 仓库内开展量化、部署、评测工作的开发者或 Agent 维护者而言，理解这三点就等于拿到了这套工具链的完整操作手册：安装入口看 README.md，目录与发现机制看 .agents/README.md，Skill 编辑规则与同步流程则遵循 AGENTS.md 与 .agents/scripts/sync-upstream-skills.sh。如果你需要在个人工作区保留私有配置，请务必记住：Claude Code 用追加，Codex 用替换且必须重述共享指令。