agnix: a linter and LSP for agent configuration files

The failure agnix targets: configs that are accepted but ignored

Agent configuration files rarely fail loudly. A SKILL.md with a name field in the wrong case, a hook that never fires, an MCP block with a typo in a key: the tool starts, reads what it can, and proceeds. The README frames this as the central problem, quoting Vercel research that skills invoke at 0% without correct syntax, and citing a Stack Overflow survey figure that 66% of developers name 'almost right' output as their biggest AI frustration. agnix's answer is a static checker for the configuration layer rather than the model layer. The README states the project carries 455 rules spanning Claude Code, Codex CLI, OpenCode, Cursor and Copilot, and that those rules are sourced from official specs, academic research and what it calls real-world breakage patterns. The audience is narrow and identifiable: teams that maintain agent instructions as versioned files, especially when several assistants are configured in the same repository and each expects a different format.

The rule namespace is the architecture

agnix is organised around prefixed rule families rather than around file types. The supported tools table in the README assigns AS-* and CC-SK-* to Agent Skills (31 rules), CC-* to Claude Code (53 rules), COP-* to GitHub Copilot (6 rules) and CUR-* to Cursor (16 rules). Claude Code's 53 rules cover CLAUDE.md, hooks, agents and plugins; Cursor's 16 cover .cursor/rules/*.mdc, .cursorrules, .cursor/hooks.json, .cursor/agents/**/*.md and .cursor/environment.json. That prefix scheme is what makes the tool legible in output: a diagnostic like MCP-018 tells you which family of assumptions produced it, and agnix explain MCP-018 is documented to print the rule and its evidence. The cost of this design is that coverage is uneven by construction. Copilot gets 6 rules and Cursor 16, while Claude Code gets 53, which reflects where the maintainers have invested rather than where your repository happens to have risk. A Copilot-only shop is getting a thin checker.

Running it: the CLI surface and the fix tiers

The README's quick start is a single command: npx agnix . against the current directory. Installation options are npm install -g agnix, brew tap agent-sh/agnix && brew install agnix, pip install agnix (or uvx agnix . to run without installing), and cargo install agnix-cli, with pre-built binaries on the releases page. The interesting part of the interface is the fix model. There are three distinct modes: agnix --fix . applies only safe fixes, agnix --fix-safe . is the explicit safe-only form, and agnix --fix-unsafe . applies all fixes including those the project labels medium and LOW confidence. agnix --dry-run --show-fixes . previews fixes with inline diff output, which is the flag to reach for before letting anything rewrite files you review by hand. Other flags include agnix --strict . (warnings become errors) and agnix --format github . for GitHub Actions annotations. Tool filtering is moving: the README describes --target claude-code and --target kiro as legacy target presets and points at tools = [...] for tool-only filtering, so scripts written against --target should be treated as carrying a migration debt. The sample output shows the diagnostic shape, including a fixable warning on a generic CLAUDE.md instruction and a fixable error on an invalid skill name such as 'Review-Code' where the help text asks for lowercase letters and hyphens.

Editor integration and the LSP claim

The project describes itself as an LSP and ships editor packages rather than leaving diagnostics to the terminal. The README lists a VS Code extension on the Visual Studio Marketplace, a JetBrains plugin, a Neovim setup expressed as { "agent-sh/agnix", config = function() require("agnix").setup() end }, and a Zed extension found by searching 'agnix' in Extensions. There is also a GitHub Action, used as agent-sh/agnix@v0 with a target input such as target: 'claude-code', and a browser playground at agent-sh.github.io/agnix/playground that the README says runs without installation. Two caveats are worth stating plainly. First, the material describes the LSP as existing and lists clients, but gives no detail on which LSP capabilities are implemented, so whether you get hover text, code actions or only diagnostics cannot be confirmed from what is here. Second, the GitHub Action example pins @v0 while the latest listed release is v0.52.2, so the action reference is a floating major tag rather than a fixed version; if reproducibility matters to you, pin the full version yourself.

Where agnix is the wrong tool

The rule set is opinionated, and the sample output shows how far that goes: a CLAUDE.md line reading 'Be helpful and accurate' is flagged as a generic instruction with the help text 'Remove generic instructions. Claude already knows this.' That is a style judgement about prompt authorship, not a correctness check, and it will fire on files that work fine for their authors. The --fix-unsafe tier compounds this, since it applies fixes the project itself rates as low confidence; running it across a repository you did not write is a way to have someone else's conventions written into your prompts. There is also a coverage boundary. The README's supported tools table is truncated mid-row for Kiro, so the full tool list cannot be verified from this material, and the rule counts that are visible range from 6 to 53 per tool. If your stack includes an assistant outside the documented families, agnix will simply have nothing to say about it, and a clean exit code will mean 'no rules matched', not 'your config is correct'. Finally, the README states that new rules and tool support ship constantly. That is a maintenance signal as much as a feature: rule identifiers and severities can shift between releases, and a pinned CI version is the only way to keep a green build green on purpose.

Alternatives and the difference in approach

The obvious comparison is to a general-purpose linter such as ESLint or a Markdown linter run over the same files. Those tools check syntax, links, heading structure and formatting; they have no concept of a skill name field, an MCP server block or a hook entry, so they cannot tell you that a skill will not trigger. agnix's rules are derived from the specifications of the assistants themselves, which is why the diagnostic can name the offending field and, in the sample, suggest the exact replacement form. The trade-off runs the other way too: a Markdown linter's rules are stable and widely understood, while agnix's rules track tools that change on their own release cadence. Editor-native validation is another partial substitute, since VS Code and JetBrains already surface JSON schema errors in settings files, but that only covers files with a published schema, and SKILL.md and CLAUDE.md are prose with conventions rather than schemas. The honest summary is that agnix occupies a category that mostly did not exist before: static analysis for the instruction layer of coding agents.

Licence, maintenance and upgrade cost

The repository is Apache-2.0 per the project metadata, and the README's own badge and link point at a LICENSE-MIT file with an MIT/Apache-2.0 label. Those two signals disagree, so the licence text in the repository is the thing to read before you depend on it; this is a factual discrepancy in the material, not a legal conclusion, and I am not giving legal advice. On maintenance, the release cadence is the real cost driver. The listed releases are v0.52.2 on 2026-09-05, v0.52.1 on 2026-08-27 and v0.52.0 on 2026-08-27, with the last push to the repository on 2026-09-09. Three releases inside a fortnight, at a 0.x version, means the project is moving quickly and has not declared a stable interface. Practically, that argues for pinning exact versions in CI rather than tracking a major tag, and for reading the changelog between bumps when a rule that used to pass starts failing. The distribution channels also carry their own upgrade paths: npm, Homebrew, pip and Cargo will each pull a different version at a different time, so a team that installs via npm locally and via the GitHub Action in CI can end up with two rule sets comparing notes in the same pull request.

Editorial conclusion

Adopt agnix if your repository carries CLAUDE.md, SKILL.md, hook or MCP configuration that more than one person edits and that you cannot easily test by hand. Skip it if your agent setup is a single prose file you rewrite weekly, since the rule set encodes other people's conventions, not yours. Before wiring it into CI, run agnix explain on two or three rules that fire in your tree and confirm the cited evidence matches your working assumptions, then check whether --strict turns warnings you consider cosmetic into build failures.

Official sources

1. agent-sh/agnix on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases