agnix: a linter and LSP for CLAUDE.md, AGENTS.md and SKILL.md

The failure mode agnix targets: configs that are syntactically fine and semantically ignored

An agent configuration file rarely fails loudly. A skill with a capitalised name, a hook with a mistyped key, an MCP server entry with a field in the wrong place: the file parses, the tool starts, and nothing happens. The README quotes Vercel research stating that skills invoke at 0% without correct syntax, and cites a Stack Overflow survey in which 66% of developers name "almost right" output as their biggest AI frustration. Whether those numbers generalise is arguable, but the underlying complaint is recognisable to anyone who has watched a skill silently not fire.

The audience is narrow and specific. If you maintain a repository with a CLAUDE.md, a .claude/skills directory, .cursor/rules, or an MCP server list, and more than one assistant reads those files, agnix is aimed at you. The README's own framing of the multi-tool problem is that Cursor, Claude Code and Copilot each want different formats, so a config that satisfies one can be wrong for another. A single linter that knows all the schemas is a reasonable answer to that.

How agnix works: rule prefixes, targets and the fix confidence ladder

agnix is a Rust workspace split into crates: agnix-core, agnix-rules, agnix-cli, agnix-lsp, agnix-mcp and agnix-wasm, plus a standalone WASM crate for the Zed extension that is excluded from the workspace. That split explains the product surface. The CLI and the LSP share the same rule engine, and the WASM crate is what lets the playground run in a browser with no install.

Rules are namespaced by the tool they apply to. Agent Skills rules are AS-* and CC-SK-*, Claude Code rules are CC-*, Copilot rules are COP-*, and Cursor rules are CUR-*. The README gives counts per tool: 31 for Agent Skills, 53 for Claude Code, 6 for Copilot and 16 for Cursor, with the headline figure of 455 rules overall. Rule identifiers are stable enough to be looked up directly: `agnix explain MCP-018` prints a rule and the evidence behind it.

Fixes are graded rather than binary. `--fix` applies only safe fixes, `--fix-safe` is the explicit form of the same mode, and `--fix-unsafe` applies everything including medium and low confidence changes. That three-level design is the most consequential choice in the tool. A linter that rewrites CLAUDE.md prose is editing instructions an agent will follow, so separating mechanical fixes from judgement calls is the right instinct. It also means the default `--fix` will leave a meaningful share of warnings unresolved, which is easy to misread as a bug.

Installing agnix and running a first validation

The README lists four install paths. npm is described as recommended and covers all platforms; Homebrew is for macOS and Linux; pip works, and `uvx agnix .` runs it without installing; Cargo installs the agnix-cli crate directly. Pre-built binaries are on the releases page.

npm install -g agnix

Once the binary is on your PATH, point it at a directory. The README's quick start runs it against the current directory and shows the shape of the output: a file and line, a severity, the rule, and a `[fixable]` marker where a fix exists.

agnix .

The example output in the README reports a generic instruction warning in CLAUDE.md at line 15, an invalid skill name error in .claude/skills/review/SKILL.md at line 3, a summary line of one error and one warning, and a hint to run with --fix, --fix-safe or --fix-unsafe. Before applying anything, preview it. The README documents a dry run that prints inline diffs.

agnix --dry-run --show-fixes .

If the diff looks right, apply the safe subset first. Reaching for --fix-unsafe on the first pass is the mistake worth avoiding, because that mode includes low confidence changes to files that steer an agent's behaviour.

agnix --fix .

Where agnix stops being the right tool

agnix validates configuration, not code. It will not tell you whether the Python or TypeScript in the same repository is correct, and it has nothing to say about the runtime behaviour of an MCP server beyond the shape of its configuration entry. Teams looking for a general project linter should not add agnix to that slot.

Rule coverage is uneven by design, because it tracks how much each vendor has specified. Claude Code carries 53 rules and Cursor 16, while Copilot carries 6. A Copilot-heavy team gets a much thinner check than a Claude Code team, and the README's supported-tools table makes that asymmetry visible rather than hiding it. The `--target` flag is also narrower than its name suggests: the README states it is a legacy target preset that primarily affects CC-* rules, and points readers to `tools = [...]` for tool-only filtering. Anyone expecting `--target` to scope the whole rule set should read that line before filing a bug.

Fix confidence is the other boundary. Because the safe mode deliberately declines medium and low confidence changes, a clean `--fix` run does not mean a clean config. The README's own example ends with unresolved issues and a hint to escalate. Treating safe-mode output as a pass/fail gate will undercount real problems.

agnix compared with running each vendor's own tooling

The obvious alternative is not another linter. It is using whatever each vendor ships: Claude Code's own validation for CLAUDE.md and skills, Cursor's checks for .mdc files, and so on. That approach has one real advantage, which is that the vendor is the authority on its own format and will update first when a schema changes.

agnix takes the opposite position. It is a single rule set, sourced in the README's words from official specs, academic research and real-world breakage patterns, covering many vendors at once. The practical difference shows up in a mixed repository. With per-vendor tooling you run three or four checks, each with its own output format and exit codes, and you reconcile them yourself. With agnix you run one command, get one severity model, and can emit GitHub Actions annotations with `--format github` or gate a pull request through the agent-sh/agnix@v0 action. The cost is latency on new syntax: a vendor can change a field before agnix has a rule for it, and you are relying on the project to track that. The README's own note that new rules and tool support ship constantly is an admission of that race.

Maintenance, licensing and the pre-commit shim

The repository is not archived and the last push was on 2026-09-09, with v0.52.2 released on 2026-09-05 and v0.52.0 and v0.52.1 both on 2026-08-27. Release cadence over that window is frequent, and the README describes the project as shipping new rules and tool support constantly. That is a maintenance cost as well as a benefit: rule sets that grow steadily can introduce new warnings against existing files, so a CI gate pinned to a floating version will eventually fail on a config nobody touched. Pinning to a release tag is the safer default.

Licensing is dual: the Cargo workspace declares `MIT OR Apache-2.0`, the README badge says MIT/Apache-2.0, and both LICENSE-MIT and LICENSE-APACHE are present at the repository root. The npm and crates.io packages are separate distribution channels for the same tool. One detail worth knowing is the root pyproject.toml, which is not a published package. Its own comments describe it as a pre-commit shim named agnix-pre-commit, deliberately distinct from the published pypi/ package so the two cannot collide on PyPI. It pins `agnix==0.53.0` exactly so that a hook pinned at a given revision always runs the matching agnix version, with scripts/sync-versions.sh keeping the numbers in step. If you use the pre-commit hook, that pinning is what protects you from the drift described above. None of this is legal advice; read both licence files if the distinction matters to your organisation.

Editorial conclusion

Adopt agnix if your repository carries CLAUDE.md, SKILL.md, .cursor/rules or MCP configuration and you want a single check that covers all of them, especially before a multi-tool team standardises on one format. Do not adopt it expecting to lint the application code around those files, and do not run --fix-unsafe on a config directory you have not committed first. Verify two things before wiring it into CI: which rule prefixes your tool actually triggers, since the README notes that --target primarily affects CC-* rules, and what the default confidence threshold is for the fixes agnix proposes in your files.

Frequently asked questions

Official sources

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