USP

This linter uniquely offers 418 rules covering Claude Code, Cursor, Copilot, and other AI tools, with auto-fix capabilities and integrations for popular IDEs and GitHub Actions. It prevents agent configuration issues from silently breaking…

Use cases

• 01Validating Claude Code SKILL.md and CLAUDE.md files
• 02Linting AI agent configurations before deployment
• 03Ensuring multi-tool AI stack compatibility
• 04Auto-fixing common agent configuration errors
• 05Integrating agent config validation into CI/CD pipelines

Detected files (8)

• tests/fixtures/invalid/skills/agent-without-context/SKILL.mdskill
  Show content (213 bytes)

  ---
  name: agent-without-context-skill
  description: Use when testing agent without context validation
  agent: Explore
  ---
  
  This skill has an agent field but no context: fork.
  The agent field requires context: fork.
  

• tests/fixtures/invalid/skills/context-without-agent/SKILL.mdskill
  Show content (212 bytes)

  ---
  name: context-without-agent-skill
  description: Use when testing context without agent validation
  context: fork
  ---
  
  This skill has context: fork but no agent field.
  The context: fork requires an agent field.
  

• tests/fixtures/invalid/skills/deploy-prod/SKILL.mdskill
  Show content (131 bytes)

  ---
  name: deploy-prod
  description: Deploys to production
  allowed-tools: Bash Read Write
  ---
  
  Deploy the application to production.
  

• tests/fixtures/invalid/skills/fork-no-instructions/SKILL.mdskill
  Show content (259 bytes)

  ---
  name: reference-skill
  description: Use when looking up documentation
  context: fork
  agent: general-purpose
  ---
  This is a reference document about the API.
  It contains information about endpoints and data models.
  The system architecture is described below.
  

• skills/agnix/SKILL.mdskill
  Show content (2341 bytes)

  ---
  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 418 rules."
  allowed-tools: Bash(agnix:*), Bash(cargo:*), Read, Glob, Grep
  ---
  
  # agnix
  
  Lint agent configurations before they break your workflow. Validates Skills, Hooks, MCP, Memory, Plugins across Claude Code, Cursor, GitHub Copilot, and Codex CLI.
  
  ## When to Use
  
  Invoke when user asks to:
  - "Lint my agent configs"
  - "Validate my skills"
  - "Check my CLAUDE.md"
  - "Validate hooks"
  - "Lint MCP configs"
  - "Fix agent configuration issues"
  
  ## Supported Files
  
  | File Type | Examples |
  |-----------|----------|
  | Skills | `SKILL.md` |
  | Memory | `CLAUDE.md`, `AGENTS.md` |
  | Hooks | `.claude/settings.json` |
  | MCP | `*.mcp.json` |
  | Cursor | `.cursor/rules/*.mdc` |
  | Copilot | `.github/copilot-instructions.md` |
  
  ## Execution
  
  ### 1. Check if agnix is installed
  
  ```bash
  agnix --version
  ```
  
  If not found, install:
  ```bash
  cargo install agnix-cli
  ```
  
  ### 2. Validate
  
  ```bash
  agnix .
  ```
  
  ### 3. If issues found and --fix requested
  
  ```bash
  agnix --fix .
  ```
  
  ### 4. Re-validate to confirm
  
  ```bash
  agnix .
  ```
  
  ## CLI Reference
  
  | Command | Description |
  |---------|-------------|
  | `agnix .` | Validate current project |
  | `agnix --fix .` | Auto-fix issues |
  | `agnix --strict .` | Treat warnings as errors |
  | `agnix --target claude-code .` | Only Claude Code rules |
  | `agnix --target cursor .` | Only Cursor rules |
  | `agnix --watch .` | Watch mode |
  | `agnix --format json .` | JSON output |
  
  ## Output Format
  
  ```
  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)
  ```
  
  ## Common Issues & Fixes
  
  | Issue | Solution |
  |-------|----------|
  | Invalid skill name | Use lowercase with hyphens: `my-skill` |
  | Generic instructions | Remove "be helpful", "be accurate" |
  | Missing trigger phrase | Add "Use when..." to description |
  | Directory/name mismatch | Rename directory to match `name:` field |
  
  ## Links
  
  - [GitHub](https://github.com/agent-sh/agnix)
  - [Rules Reference](https://avifenesh.github.io/agnix/docs/rules)
  

• tests/fixtures/invalid/skills/argument-hint-no-args/SKILL.mdskill
  Show content (156 bytes)

  ---
  name: hint-skill
  description: Use when testing argument hints
  argument-hint: <file-path>
  ---
  This skill body does not reference the arguments variable.
  

• plugin/skills/agnix/SKILL.mdskill
  Show content (4018 bytes)

  ---
  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 418 rules across 10+ AI tools."
  argument-hint: "[path] [--fix] [--strict] [--target=claude-code|cursor|codex]"
  allowed-tools: Bash(agnix:*), Bash(cargo:*), Read, Glob, Grep
  ---
  
  # agnix
  
  Lint agent configurations before they break your workflow. Validates Skills, Hooks, MCP, Memory, Plugins across 10+ AI tools including Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, Gemini CLI, Cline, Windsurf, Kiro, and Amp.
  
  ## Parse Arguments
  
  ```javascript
  const args = '$ARGUMENTS'.split(' ').filter(Boolean);
  const targetPath = args.find(a => !a.startsWith('--')) || '.';
  const fix = args.includes('--fix');
  const strict = args.includes('--strict');
  let target = args.find(a => a.startsWith('--target='))?.split('=')[1];
  if (!target) {
    const idx = args.indexOf('--target');
    if (idx !== -1 && args[idx + 1]) target = args[idx + 1];
  }
  target = target || 'claude-code';
  ```
  
  ## When to Use
  
  Invoke when user asks to:
  - "Lint my agent configs"
  - "Validate my skills"
  - "Check my CLAUDE.md"
  - "Validate hooks"
  - "Lint MCP configs"
  - "Fix agent configuration issues"
  - "Check if my SKILL.md is correct"
  
  ## Prerequisites
  
  agnix must be installed. Check with:
  ```bash
  agnix --version
  ```
  
  If not installed:
  ```bash
  cargo install agnix-cli
  ```
  
  ## Execution
  
  ### 1. Validate Project
  
  ```bash
  agnix .
  ```
  
  ### 2. If Issues Found and Fix Requested
  
  ```bash
  agnix --fix .
  ```
  
  ### 3. Re-validate to Confirm
  
  ```bash
  agnix .
  ```
  
  ## CLI Reference
  
  | Command | Description |
  |---------|-------------|
  | `agnix .` | Validate current project |
  | `agnix --fix .` | Auto-fix issues |
  | `agnix --strict .` | Treat warnings as errors |
  | `agnix --target claude-code .` | Only Claude Code rules |
  | `agnix --target cursor .` | Only Cursor rules |
  | `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 Format
  
  ```
  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 Issues & 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 |
  
  ## Integration
  
  This skill is standalone and can be invoked directly via `/agnix`.
  
  For CI integration, see 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)
  

• tests/fixtures/invalid/skills/first-person-description/SKILL.mdskill
  Show content (116 bytes)

  ---
  name: first-person-description
  description: Use when you need pull-request review help
  ---
  Review changed files.

README

agnix

Lint agent configurations before they break your workflow

Catch broken agent configs before your AI tools silently ignore them.
418 rules across Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and more -
validating CLAUDE.md, SKILL.md, hooks, MCP configs, and other agent files.

Auto-fix | GitHub Action | VS Code + JetBrains + Neovim + Zed

New rules and tool support ship constantly. Follow for real-time updates:

Why agnix?

Your skills don't trigger. Vercel's research found skills invoke at 0% without correct syntax. One wrong field and your skill is invisible.

"Almost right" is the worst outcome. 66% of developers cite it as their biggest AI frustration. Misconfigured agents produce exactly this.

Multi-tool stacks fail silently. Cursor + Claude Code + Copilot each want different formats. A config that works in one tool breaks in another.

Bad patterns get amplified. AI assistants don't ignore wrong configs - they learn from them.

agnix validates all of it - 418 rules sourced from official specs, academic research, and real-world breakage patterns. Auto-fix included.

Want to try it first? Open the playground - paste any agent config, see diagnostics instantly. No install, runs in your browser.

Quick Start

$ npx agnix .
Validating: .

CLAUDE.md:15:1 warning: Generic instruction 'Be helpful and accurate' [fixable]
  help: Remove generic instructions. Claude already knows this.

.claude/skills/review/SKILL.md:3:1 error: Invalid name 'Review-Code' [fixable]
  help: Use lowercase letters and hyphens only (e.g., 'code-review')

Found 1 error, 1 warning
  2 issues are automatically fixable

hint: Run with --fix, --fix-safe, or --fix-unsafe to apply fixes

https://github.com/user-attachments/assets/72d5fe7c-476f-46ea-be64-5785cf6d5600

Install

# npm (recommended, all platforms)
npm install -g agnix

# Homebrew (macOS/Linux)
brew tap agent-sh/agnix && brew install agnix

# Cargo
cargo install agnix-cli

Pre-built binaries | All install options

Editor Extensions

Editor	Install
VS Code	VS Code Marketplace
JetBrains	JetBrains Marketplace
Neovim	{ "agent-sh/agnix", config = function() require("agnix").setup() end }
Zed	Search "agnix" in Extensions

Editor setup guide

GitHub Action

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

Usage

agnix .              # Validate current directory
agnix --fix .        # Apply HIGH and MEDIUM confidence fixes
agnix --fix-safe .   # Apply only HIGH confidence fixes
agnix --fix-unsafe . # Apply all fixes, including LOW confidence
agnix --dry-run --show-fixes .  # Preview fixes with inline diff output
agnix --strict .     # Strict mode (warnings = errors)
agnix --target claude-code .  # Legacy target preset (primarily affects CC-* rules)
agnix --target kiro .         # Legacy target preset (use tools = [...] for tool-only filtering)

Full CLI reference | Full rules reference

Supported Tools

Tool	Rules	Count	Config Files
Agent Skills	AS-*, CC-SK-*	31	SKILL.md
Claude Code	CC-*	53	CLAUDE.md, hooks, agents, plugins
GitHub Copilot	COP-*	6	.github/copilot-instructions.md, .github/instructions/*.instructions.md
Cursor	CUR-*	16	.cursor/rules/*.mdc, .cursorrules, .cursor/hooks.json, .cursor/agents/**/*.md, .cursor/environment.json
Kiro	KIRO-*, KR-SK-*, KR-AG-*, KR-HK-*, KR-PW-*, KR-MCP-*	51	.kiro/steering/**/*.md, .kiro/skills/**/SKILL.md, .kiro/agents/*.json, .kiro/hooks/*.kiro.hook, .kiro/settings/mcp.json, .kiro/powers/*/POWER.md
MCP	MCP-*	12	*.mcp.json
AGENTS.md	AGM-*, XP-*	13	AGENTS.md, AGENTS.local.md, AGENTS.override.md
Cline	CLN-*	4	.clinerules, .clinerules/*.md, .clinerules/*.txt
Gemini CLI	GM-*	9	GEMINI.md, GEMINI.local.md, .gemini/settings.json (hooks), gemini-extension.json (extensions), .geminiignore

Architecture

Rust workspace crates:

• agnix-rules - rule metadata generated from knowledge-base/rules.json
• agnix-core - shared validation engine library
• agnix-cli - command-line interface binary
• agnix-lsp - language server binary
• agnix-mcp - MCP server binary
• agnix-wasm - WebAssembly bindings for browser/runtime integrations

Contributing

Contributions welcome. See CONTRIBUTING.md for the development guide.

Report a bug | Request a rule | Good first issues

License

MIT OR Apache-2.0

---

Star this repo to help other developers find agnix.