# agnix tested: a free linter for AI agent config files

Canonical: https://www.kartikaydhar.com/blog/agnix-agent-config-linter-tested
Published: 2026-11-16T13:42:23+00:00
Updated: 2026-11-16T02:33:16.569284+00:00
Category: Tool Breakdowns

I ran agnix 0.61.0 on a project I broke on purpose and 13 of my own skills. It caught every planted mistake, but most fixes still need a person.

agnix is a free, open-source linter from the agent-sh project for the setup files that tell AI coding assistants how to behave. A linter is a tool that reads files and flags mistakes before they cause trouble, a bit like spellcheck. I ran it on a project I broke on purpose and on 13 of my own skill files, which are instruction files that teach an assistant a specific task. It found every mistake I planted and two real errors in one of my skills, in under a tenth of a second. The catch is that fixing is mostly up to you. Its cautious fix mode fixed just one of the eight findings in my test project. The bolder mode also deleted a line from CLAUDE.md, the file of project rules that Claude Code reads. Everything else needed a person.

The problem it targets is setup that breaks without telling you. The README's pitch is to "catch broken agent configs before your AI tools silently ignore them."

## What I tested

- Version: agnix 0.61.0, the latest release (published 4 November 2026), installed from npm, the Node.js package installer.
- Setup: one install command. It took about 2 seconds and needed no account, sign-up or key.
- Task I ran: two checks. First, a small project I broke on purpose with six planted mistakes. Second, copies of 13 real skill files from my own setup. Then I previewed and applied its automatic fixes on copies.
- Time to first result: each check finished in 45 to 96 milliseconds when I ran the program directly, and about 0.2 seconds through npx, the Node.js command for running a tool without setting it up first, which adds start-up time.
- What worked: it caught all six planted mistakes and pointed to the exact line and character in each file.
- What broke or surprised me: the safe fix mode changed one file in the test project and nothing in my own skills. One mistake the README's own example calls an error came back as a warning.

## What are agent config files, and what is agnix?

AI coding assistants such as Claude Code, Codex and Cursor read plain text files in your project to learn the rules. The common ones are:

- CLAUDE.md and AGENTS.md: notes of project rules the assistant reads when it starts, like "run the tests before committing."
- Skills: folders with a SKILL.md file of instructions the assistant loads when a task matches, like a recipe card.
- Hooks: commands the assistant runs automatically at set moments, for example after it edits a file.
- MCP configs: MCP, the Model Context Protocol, is the standard way an assistant connects to outside tools and data. The config lists which tools to connect and how.

agnix checks all of these. The README says it has 761 rules, "sourced from official specs, academic research, and real-world breakage patterns." They aren't spread evenly. By the README's own counts, Claude Code has 170 tool-specific rules, Codex CLI 89, Cursor 40 and GitHub Copilot 35. It's written in Rust, a programming language, and it is licensed MIT or Apache 2.0, your choice. The repo had 484 stars, GitHub's bookmarks and a rough sign of interest, when I checked on 16 November 2026.

It also works inside code editors such as VS Code, underlining mistakes as you type, and as a GitHub check that runs on every proposed change. I used only the command-line version.

## What did it catch in a project I broke on purpose?

I made a small project with a CLAUDE.md, a settings file with hooks, an MCP config and two skills. Then I planted six mistakes, the kind that are easy to make by hand or by copying from an old example.

Image: Illustration: What did it catch in a project I broke on purpose?

What agnix 0.61.0 reported on my broken test project, redrawn from the terminal output.

It reported 2 errors, 4 warnings and 2 info notes.

### The two errors

The first was a hook set to run on "OnSave". That isn't an event Claude Code knows about. agnix said so and printed the 33 event names that are valid.

The second was an MCP tool marked as a web connection but with no web address. agnix flagged that the required url field was missing.

### The four warnings

One MCP tool had an API key, a password that lets software use a paid service, typed straight into the file. That kind of secret can end up by accident in a shared repo, the code folder a whole team works from. agnix flagged it as "a literal secret."

The same tool was set to download whatever its latest version is each time it starts, with no version number fixed. agnix called that a server "without a pinned version." Pinning means naming the exact version so it can't change under you.

A skill was named "Review-Code". Skill names should be kebab-case, meaning lowercase words joined by hyphens, like review-code. The README's own Quick Start example shows this exact name as an error, but version 0.61.0 reported it as a warning and explained why: Claude Code loads it, but the Claude API (how developers connect their own software to Claude) and claude.ai "require lowercase letters, numbers and hyphens."

The CLAUDE.md said "Be helpful and accurate." agnix flagged that as a generic instruction that "adds no project-specific guidance."

### The two info notes

One said a skill description said what the skill does but not when to use it. The other said I hadn't told agnix which tool versions I use, so it was applying default assumptions.

## What did it find in my own skills?

Next I ran it on copies of 13 skill files from my own setup. It checked 18 files in total and returned 2 errors, 1 warning and 2 info notes.

Both errors came from one skill. I had named it with capitals and spaces, "Intelligent Claude Delegation", while its folder is intelligent-claude-delegation. agnix said the name must be lowercase letters, digits and hyphens, and that it must match the folder name. The Agent Skills specification says the same. An info note added that the word "claude" in a skill name is reserved, so claude.ai and the Claude API reject the skill on upload.

The warning was for my longest skill, a writing guide, at 549 lines. The Agent Skills specification says to keep the main SKILL.md under 500 lines and move detailed reference material into separate files.

## Can it fix things for you?

Some things. Each fix comes with a confidence level. Plain --fix applies only the high-confidence ones. --fix-unsafe applies medium and low ones too. "Unsafe" here means fixes agnix is less sure of, and they can delete or rename things. --dry-run shows what would change without touching anything, so you can check before anything changes.

Image: Illustration: Can it fix things for you?

What each fix mode changed on copies of my files.

On the broken project, the safe fix renamed "Review-Code" to "review-code" and nothing else. The unsafe fix also deleted the "Be helpful" line from CLAUDE.md, which agnix rated 80% confident.

On my own skills, the safe fix changed nothing. The rename from "Intelligent Claude Delegation" to "intelligent-claude-delegation" was also rated 80% confident, so it only happened with --fix-unsafe. After that, both errors were gone. The note about the reserved word "claude" stayed, because the new name still contains it.

The bad hook, the missing address, the secret key, the unpinned tool and the long skill had no automatic fix. Those need someone to decide what the right setting is.

## What this means for product and GTM teams

If your team uses AI coding assistants, these setup files are now part of how work gets done. They decide which rules the assistant follows, which tools it can reach and what runs automatically. They get edited by hand, copied between projects and rarely reviewed. The mistakes I planted are ordinary typos and leftovers, and the two real errors were in my own skill files.

A linter gives those files the same kind of check that code already gets. Because agnix is free, needs no account and runs in a fraction of a second, it fits into a normal review: run it before a change is merged, or add the GitHub Action so it runs every time. For a product team, that is a QA step for assistant setup that costs nothing to try.

The things to watch are the ones my test showed. Trust what the tool reports over the README's examples, which don't match the tool in at least one place: the Quick Start shows "Review-Code" as an error, and 0.61.0 reports a warning. Preview fixes before applying them, because two of the three fixes in my test needed the unsafe flag. And expect most findings to need a human decision.

If you write your own skills, my posts on building a personal Claude skill with Skill Cauldron and on harness engineering cover the files agnix checks. For checking what an assistant does after setup, see tester-army turning agent clicks into test lines.

## How do I try it?

This is a few minutes of work for anyone comfortable typing a command, and a good first test is your own project's setup files. You need Node.js installed. From the project folder:

npx agnix .

To preview fixes without changing files:

npx agnix --dry-run \
  --show-fixes .

To run it on every proposed change on GitHub, the README gives this step:

- name: Validate agent configs
  uses: agent-sh/agnix@v0
  with:
    target: 'claude-code'

Change claude-code to the assistant your team uses. The Action accepts generic, claude-code, cursor and codex.

Success looks like a list of findings with file names and line numbers, ending in a summary such as "Found 2 errors, 4 warnings." The browser playground lets you paste a single file and see results without installing anything. It can also be installed with Homebrew, a common installer on Macs.

Usage reporting is off unless you switch it on. In my install, agnix telemetry status showed it as disabled.

## Frequently asked questions

### Is agnix free?

Yes. It's open source under the MIT or Apache 2.0 license, and I installed and ran it with no account or key.

### Which AI tools does it support?

The README lists Claude Code, Codex CLI, Kiro, OpenCode, Cursor, GitHub Copilot, Gemini CLI, Cline and others, ranked in five maintenance tiers from S to D. The project's contributing guide defines S as "test always" and D as "nice-to-have maintenance", which means keeping existing checks and fixing reported problems. Claude Code and Codex CLI are in tier S and get the most attention. Cursor and GitHub Copilot are in tier D, the lowest, so expect fewer checks there. I tested only Claude Code style files and skills.

### Will it change my files without asking?

Only if you use --fix or --fix-unsafe. A plain run only reports. Add --dry-run to see the changes first.

### How fast is it?

Each of my checks took 45 to 96 milliseconds when run directly, and about 0.2 seconds through npx, on folders of 5 and 18 files.

## Sources

- agent-sh/agnix on GitHub (README, checked 16 November 2026)
- agnix releases (v0.61.0, 4 November 2026)
- agnix on npm
- agnix rules reference
- agnix GitHub Action
- agnix contributing guide: tool tier system
- agnix GitHub Action settings (action.yml)
- Agent Skills specification
