Skip to main content
subagent CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/agnix-agent.md
Open on GitHub

What 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 .md and .toml files
  • 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 /agnix with 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.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set5

Project sponsors

Companies that keep this analytics open