agnix — Claude Code skill: lint agent config files
Checks skills, hooks, MCP servers and memory files before they break your workflow. One command inside the project.
npx skills add agent-sh/agnix --skill agnix -a claude-codeWhat agnix does
agnix walks the agent's config files and checks them against a rule set: skill naming, trigger phrases in the description, hook settings, MCP tool definitions, the shape of AGENTS.md. It catches the usual suspects — a skill name in capitals, a directory that does not match the name: field, a line like “be helpful” sitting in CLAUDE.md. Rules carry prefixes: AS-* for skills, CC-* for Claude, MCP-* for the protocol, PE-* for prompt quality, XP-* for cross-tool compatibility.
Run agnix . at the project root, add --strict when warnings should fail the run. The --fix flag applies safe corrections; agnix --dry-run . shows the list first. Skip --fix and nothing on disk changes. Pick a tool with --target claude-code — leave it out and the CLI falls back to generic. There is a watch mode, plus JSON and SARIF output, the latter for GitHub Code Scanning.
The CLI is a separate install from the skill: npm install -g agnix or cargo install agnix-cli, with Homebrew and PyPI builds available. Exit codes are plain: 0 for a clean run, 1 when errors turn up, 2 for bad arguments. A GitHub Action ships in the repo for CI.
What it helps with
- catch a malformed skill name before the agent runs
- match a skill directory to its
name:field - strip generic filler out of
CLAUDE.md - check hook settings and MCP server configs
- run config checks in CI and fail on warnings
Example prompts for the agent
- Lint the agent configs in this project:
agnix . - Run a strict pass with auto-fixes:
agnix --fix --strict . - Preview what would be fixed, change nothing:
agnix --dry-run .
How to install agnix
1Skills CLI (Vercel)
npx skills add agent-sh/agnix --skill agnix -a claude-code2Manually: put the files in place
~/.claude/skills/agnix/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agnix/
1Skills CLI (Vercel)
npx skills add agent-sh/agnix --skill agnix -a codex2Manually: put the files in place
.agents/skills/agnix/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add agent-sh/agnix --skill agnix -a cursor2Manually: put the files in place
.cursor/skills/agnix/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install agent-sh/agnix agnix2Manually: put the files in place
.github/skills/agnix/SKILL.md1Skills CLI (Vercel)
npx skills add agent-sh/agnix --skill agnix -a gemini-cli2Platform CLI
gemini skills install https://github.com/agent-sh/agnix --path plugin/skills/agnixManually: put the files in place
.devin/skills/agnix/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add agent-sh/agnix --skill agnix -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about agnix
How do I install agnix in Claude Code?
Add the skill with npx skills add agent-sh/agnix --skill agnix -a claude-code; it lands at ~/.claude/skills/agnix/SKILL.md. The CLI itself is separate: npm install -g agnix or cargo install agnix-cli.
What does agnix do?
It validates agent configuration files — skills, hooks, MCP, memory, plugins — and reports errors and warnings with file and line. Some findings are marked fixable.
What is the difference between --fix and --dry-run?
--fix writes safe auto-fixes to your files, so re-run the check afterwards. --dry-run only lists what would change and leaves everything untouched.
Source text
SKILL.md · Apache-2.0
---
name: agnix
description: "Use when user asks to 'lint agent configs', 'validate skills', 'check CLAUDE.md', 'validate hooks', 'lint MCP'. Validates agent configuration files against 702 rules across 10+ AI tools."
argument-hint: "[path] [--fix] [--strict] [--target=generic|claude-code|cursor|codex|kiro]"
allowed-tools: Bash(agnix:*), Bash(cargo:*), Read, Glob, Grep
---
# agnix
Lint agent configurations (Skills, Hooks, MCP, Memory, Plugins) before they break a workflow, across Claude Code, Codex CLI, OpenCode, Kiro, Cursor, GitHub Copilot, Cline, Gemini CLI, Windsurf, Amp and others.
Arguments, from `$ARGUMENTS`: a path (default `.`), `--fix`, `--strict`, and `--target` as `--target=X` or `--target X`. Without `--target` the CLI uses `generic`.
## Run
1. `agnix --version`. If it is missing, install with `npm install -g agnix` or `cargo install agnix-cli` (also on Homebrew and PyPI).
2. `agnix [--strict] [--target <target>] <path>`.
3. With `--fix`: `agnix --fix [--target <target>] <path>`, then run step 2 again to confirm what remains. Without `--fix`, change no files; `agnix --dry-run <path>` previews the fixes.
## CLI reference
| Command | Description |
|---------|-------------|
| `agnix .` | Validate current project |
| `agnix --fix .` | Apply safe auto-fixes |
| `agnix --dry-run .` | Show what would be fixed, change nothing |
| `agnix --strict .` | Treat warnings as errors |
| `agnix --target claude-code .` | Target one tool: `generic`, `claude-code`, `cursor`, `codex`, `kiro` |
| `agnix --watch .` | Watch mode - re-validate on changes |
| `agnix --format json .` | JSON output |
| `agnix --format sarif .` | SARIF for GitHub Code Scanning |
## Supported files
| File Type | Examples |
|-----------|----------|
| Skills | `SKILL.md` |
| Memory | `CLAUDE.md`, `AGENTS.md` |
| Hooks | `${STATE_DIR}/settings.json` |
| MCP | `*.mcp.json` |
| Cursor | `.cursor/rules/*.mdc` |
| Copilot | `.github/copilot-instructions.md` |
## Output
```
CLAUDE.md:15:1 warning: Generic instruction 'Be helpful' [fixable]
help: Remove generic instructions. Claude already knows this.
skills/review/SKILL.md:3:1 error: Invalid name [fixable]
help: Use lowercase letters and hyphens only
Found 1 error, 1 warning (2 fixable)
```
Exit codes: `0` no errors (warnings allowed), `1` errors found, `2` invalid arguments.
## Rule categories
| Prefix | Category | Examples |
|--------|----------|----------|
| AS-* | Agent Skills | Name format, triggers, description |
| CC-* | Claude Code | Hooks, memory, plugins |
| MCP-* | MCP Protocol | Server config, tool definitions |
| PE-* | Prompt Engineering | Generic instructions, redundancy |
| XP-* | Cross-Platform | Compatibility across tools |
| AGM-* | AGENTS.md | Structure, sections |
| COP-* | GitHub Copilot | Instructions format |
| CUR-* | Cursor | MDC format, rules |
## Common fixes
| Issue | Solution |
|-------|----------|
| Invalid skill name | Use lowercase with hyphens: `my-skill` |
| Directory/name mismatch | Rename directory to match `name:` field |
| Generic instructions | Remove "be helpful", "be accurate" |
| Missing trigger phrase | Add "Use when..." to description |
For CI, use the [GitHub Action](https://github.com/agent-sh/agnix#github-action).
## Links
- [GitHub](https://github.com/agent-sh/agnix)
- [Rules Reference](https://github.com/agent-sh/agnix/blob/main/knowledge-base/VALIDATION-RULES.md)
- [Configuration](https://github.com/agent-sh/agnix/blob/main/docs/CONFIGURATION.md)
© agent-sh · Apache-2.0 · agent-sh/agnix
