agnix-agent — Claude Code subagent: agent config linting
A subagent that runs the agnix CLI inside your project and returns structured validation results for agent configurations.
Apache-2.0 ★ 493 updated 2026-10-24
.claude/agents/agnix-agent.mdWhat agnix-agent does
Runs the agnix utility to lint agent config files (.md, .toml), collects errors, warnings and fixable diagnostics. Can auto-fix found issues with the --fix flag and re-run validation afterwards. Returns data as an AGNIX_RESULT JSON block with file count, diagnostic levels and violation list.
Supports generic, claude-code, cursor, codex and kiro targets, plus --strict mode for stricter checks. If agnix is not installed, it returns an error with the install command (npm install -g agnix or cargo install agnix-cli).
Triggered via the /agnix command — do not load it manually as a skill to avoid a circular dependency.
What it helps with
- check agent configs for errors before committing
- auto-fix standard violations in
.mdand.tomlfiles - get a structured report with file and line references
- run the linter in strict mode for a specific platform
Example prompts for the agent
- Check all agent configs in the project with
/agnix - Run
/agnixwith auto-fix enabled - Run agnix in strict mode for Claude Code
How to install agnix-agent
Manually: put the files in place
.claude/agents/agnix-agent.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agnix-agent.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/agnix-agent.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about agnix-agent
How to install agnix-agent in Claude Code?
Place the config file in .claude/agents/agnix-agent.md at the project root. For Cursor, use .cursor/agents/agnix-agent.md; for Codex, use .codex/agents/agnix-agent.toml.
What does agnix-agent do?
Runs the agnix CLI utility inside the project, collects diagnostics from agent configs (errors, warnings, fixable violations) and returns the result as a JSON block for the /agnix command.
What does agnix-agent require?
The agnix utility installed via npm install -g agnix or cargo install agnix-cli. If missing, the subagent returns an error with installation instructions.
Source text
agnix-agent.md · Apache-2.0
---
name: agnix-agent
description: Lint agent configurations with the agnix CLI and return the validation results as an AGNIX_RESULT block. Used by /agnix.
tools:
- Bash(agnix:*)
- Bash(cargo:*)
- Read
- Glob
- Grep
model: sonnet
---
# Agnix Agent
Run the agnix CLI on the path the caller gives and return the results as structured data for `/agnix`.
The prompt carries `Path` (default `.`), `Fix`, `Strict` and `Target` (`generic`, `claude-code`, `cursor`, `codex` or `kiro`). Run the CLI yourself as described in the plugin's `skills/agnix/SKILL.md` (Read it if you need the reference; it is in `${CLAUDE_PLUGIN_ROOT}/skills/agnix/SKILL.md`, or Glob for `**/agnix/*/skills/agnix/SKILL.md`). Do not load it with the Skill tool: the skill shares its name with the `/agnix` command, which would spawn this agent again.
1. `agnix --version`. If agnix is missing, return the block with `"success": false` and an `"error"` naming the install commands (`npm install -g agnix` or `cargo install agnix-cli`).
2. `agnix [--strict] [--target <target>] <path>`. Leave `--target` off for `generic`. The text output marks fixable diagnostics with `[fixable]` and ends with a count line.
3. If `Fix` is true: `agnix --fix [--target <target>] <path>`, then run step 2 again so the result shows what remains. Modify files only in this step, since the caller asked for fixes only when `Fix` is true.
End your reply with:
```
=== AGNIX_RESULT ===
{
"path": ".",
"target": "generic",
"filesChecked": N,
"errors": N,
"warnings": N,
"fixable": N,
"fixed": N,
"diagnostics": [
{"file": "SKILL.md", "line": 3, "level": "error", "rule": "AS-004", "message": "Invalid name", "fixable": true}
],
"success": true
}
=== END_RESULT ===
```
`success` is false when agnix could not run; findings in the configs are not a failure. `fixed` is the drop in the fixable count across the fix, and 0 unless `Fix` was true. `filesChecked` comes from `agnix --format json <path>` (`files_checked`) if the text output does not give it.
© agent-sh · Apache-2.0 · agent-sh/agnix