AI 编码工具现在不只读代码，也开始读各种“给 agent 的说明书”：AGENTS.md、CLAUDE.md、SKILL.md、.cursor/rules、MCP 配置、hooks、Copilot instructions。问题是，这些配置一旦写错，通常不会像 TypeScript 类型错误那样立刻爆红。更常见的是 agent 静默忽略某段规则，或者只在某个工具里生效，换到另一个工具就失效。

今天推荐的 agent-sh/agnix 正好补这块空白。它是一个面向 AI agent 配置文件的 linter，用 Rust 实现，提供 npm、Cargo、Homebrew、编辑器扩展、GitHub Action 和在线 playground。GitHub 搜索结果当前显示项目约有 263 stars、23 forks，主要语言为 Rust，许可证为 MIT OR Apache-2.0。npm 包 agnix 和 crates.io 包 agnix-cli 当前最新版本都是 0.29.0。

项目概览

属性详情
仓库agent-sh/agnix
npm 包agnix
Cargo 包agnix-cli
Stars约 263
Forks23
主要语言Rust
许可MIT OR Apache-2.0
当前版本v0.29.0

它解决的是“配置看起来对，但没有生效”

过去的开发工具配置大多有明确 schema。package.json、tsconfig.json、ESLint config 写错时，编辑器、CLI 或 CI 很快能提醒你。AI agent 配置的状态更松散：同样是 markdown 或 JSON，每个工具约定不同，很多规则靠文档说明而不是统一 schema。

这会带来一个很隐蔽的问题：配置文件看起来完整，agent 也能运行，但关键规则没有被加载。比如 skill 名称格式不对、frontmatter 字段不对、hook 路径不对、MCP JSON 写法不对、Copilot instructions 放错目录。开发者通常要等到 agent 行为异常时才回头查。

agnix 的定位就是把这类配置问题提前发现。README 里列出它目前覆盖 421 条规则，来源包括官方规格、研究材料和实际踩坑模式。它不是检查业务代码，而是检查那些决定 agent 如何读项目、调用工具、触发技能、执行 hook 的“元配置”。

支持的工具范围很广

agnix 的有趣之处在于，它没有只绑定某一个 agent。README 里的支持表覆盖了多种常见入口：

  • Agent Skills：检查 SKILL.md。
  • Claude Code：检查 CLAUDE.md、hooks、agents、plugins。
  • GitHub Copilot：检查 .github/copilot-instructions.md 和 instructions 文件。
  • Cursor：检查 .cursor/rules/*.mdc、.cursorrules、hooks、agents、environment 配置。
  • Kiro：检查 steering、skills、agents、hooks、MCP settings、powers。
  • MCP：检查 *.mcp.json。
  • AGENTS.md：检查 AGENTS.md、AGENTS.local.md、override 文件。
  • Cline 和 Gemini CLI：检查各自的规则、settings 和扩展配置。

这很符合现在的真实工作流。一个仓库里可能同时有 AGENTS.md、Claude Code skill、Cursor rule、Copilot instructions 和 MCP server 配置。没有统一检查工具时，团队只能靠人工 review 这些配置是否仍然符合各工具的最新约定。

agnix 把它们放进同一个 CLI 里，价值不是“替代官方文档”，而是把容易被忽略的格式、命名、位置和兼容性问题变成可运行的检查。

CLI 用法很直接

最简单的使用方式是直接用 npm：

npm install -g agnix
agnix .

也可以通过 Homebrew 或 Cargo 安装：

brew tap agent-sh/agnix && brew install agnix
cargo install agnix-cli

README 里展示的常用命令包括：

agnix .
agnix --fix .
agnix --fix-safe .
agnix --dry-run --show-fixes .
agnix --strict .
agnix --target claude-code .

这套命令的层次比较清楚。平时可以先跑 agnix . 看诊断；准备批量修改时用 --dry-run --show-fixes 预览；对自动修复不放心时，只用 --fix-safe；在 CI 里则可以开 --strict，把 warning 也当成失败。

自动修复适合放在窄范围里

agnix 支持 auto-fix，但我会建议先把它当成“辅助修复”，不要一开始就在大仓库里无脑全开。原因很简单：agent 配置文件经常带有团队语义，某些规则既有格式要求，也可能牵涉到团队约定。

比较稳妥的做法是：

  • 本地先跑 agnix .，只读诊断。
  • 用 agnix --dry-run --show-fixes . 看它准备改什么。
  • 对明显格式类问题使用 --fix-safe。
  • 把 --fix 或 --fix-unsafe 留给人工确认后的批处理。

这样既能得到 linter 的效率，又不会把团队约定交给自动工具直接重写。特别是 SKILL.md、AGENTS.md 这类文件，内容往往会影响整个 Codex 或 Claude Code 的行为，值得保守一点。

编辑器和 CI 集成让它更像基础设施

agnix 不只是一个单独 CLI。README 里列出了 VS Code、JetBrains、Neovim、Zed 扩展，以及 GitHub Action。它还提供 playground，可以在浏览器里粘贴 agent config 直接看诊断。

这说明项目的目标不是“偶尔跑一次检查”，而是把 agent 配置纳入日常开发反馈回路：

  • 写 SKILL.md 时，编辑器直接提示字段或命名问题。
  • 提交 PR 时，GitHub Action 检查 agent 配置是否破坏。
  • 升级 Claude Code、Cursor、Gemini CLI 或其他工具时，用同一个 CLI 扫一遍仓库。
  • 团队新增 MCP 配置或 hooks 时，先让 CI 验证基础结构。

对已经依赖 coding agent 的团队来说，这会慢慢变成类似 ESLint、markdownlint、actionlint 的基础检查。它不保证 agent 一定做对事，但可以先保证“说明书”没有明显坏掉。

架构偏向可复用规则引擎

从 README 的架构说明看，agnix 是一个 Rust workspace，而不是只写了一个命令行脚本。核心 crate 包括：

  • agnix-rules：从规则 JSON 生成 rule metadata。
  • agnix-core：共享验证引擎。
  • agnix-cli：命令行入口。
  • agnix-lsp：language server。
  • agnix-mcp：MCP server。
  • agnix-wasm：浏览器和 runtime 集成使用的 WebAssembly bindings。

这个拆分很合理。Agent 配置格式还在快速变化，如果规则只藏在 CLI 内部，很难复用到编辑器、web playground 或 MCP server。把规则元数据和核心验证引擎拆出来，后续更容易支持新的工具和新的文件类型。

agnix-mcp 也很值得注意。理论上，agent 可以在修改自身配置或项目指令前调用检查工具，让它不要一边写坏配置，一边继续相信坏配置已经生效。这类“agent 自我约束工具”以后应该会越来越常见。

适合什么场景

我会优先把 agnix 放进这些项目里：

  • 仓库里已经有 AGENTS.md、CLAUDE.md、SKILL.md 或 Cursor rules。
  • 团队同时使用多个 AI coding 工具，配置格式经常混在一起。
  • 你维护 Codex skills、Claude Code commands、MCP server 或 hooks。
  • PR review 里经常有人手动指出 agent 指令格式问题。
  • 想把 agent 配置纳入 CI，而不是只靠本地经验。
  • 正在做 AI coding workflow 的模板仓库或 starter kit。

如果你只是偶尔在个人项目里写一两句 agent 指令，agnix 可能显得有点重。但只要这些配置开始被团队复用，或者开始影响自动化任务、CI、部署、code review，专门的 linter 就会很有价值。

需要注意的边界

agnix 能检查的是“配置文件是否符合规则”，不是“agent 是否真的理解了你的意图”。比如它可以指出 skill metadata 不合规、hook 配置错误、某些泛泛而谈的指令可以删除，但它不能替代你判断一条工程指令是否合理。

另外，规则数量多也意味着你需要管理噪音。第一次引入时，可能会看到不少 warning。我的建议是先把 error 清掉，再决定哪些 warning 进入 CI gate。对已有大型仓库，逐步收紧比一次性严格更容易落地。

还要注意版本变化。AI coding 工具体系还在快速变，官方约定、文件路径、字段名都可能调整。agnix 的价值来自跟进这些变化，但团队自己也应该固定版本，避免 CI 在没有评估的情况下突然引入新的规则失败。

总结

agent-sh/agnix 把一个越来越常见的问题明确提了出来：AI agent 的配置也需要 lint。随着项目里出现更多 AGENTS.md、skills、MCP configs、hooks 和编辑器专用规则，手动确认它们有没有被正确加载会越来越不现实。

agnix 的路线很务实：用一个 Rust 核心检查多种 agent 配置，用 CLI、编辑器扩展、GitHub Action、MCP 和 WASM 把检查放进不同工作流。它不是让 agent 变聪明的魔法，而是让 agent 至少不要因为配置文件写错而从一开始就跑偏。

如果你的团队已经把 AI coding agent 放进真实开发流程，agnix 值得加入工具箱。先从 agnix . 和 --dry-run 开始，把 agent 配置当成需要持续维护的工程资产，而不是一次写完就遗忘的提示词文件。

项目地址：https://github.com/agent-sh/agnix