repository·main·Indexed 43 days ago
https://github.com/agent-sh/agnixAn Agent Config Linter designed to catch syntax errors and bad patterns in AI agent configuration files, including CLAUDE.md, SKILL.md, MCP configs, and Cursor rules. It provides a CLI (agnix-cli), a core library (agnix-core), and a language server (agnix-lsp) with support for VS Code, Zed, Neovim, Helix, and JetBrains IDEs.
The AI Agent Knowledge Library serves as a curated entrypoint to internal standards, validation rules, and authoritative external sources for building and configuring AI agents. Use the following resources to implement and maintain agent standards:
VALIDATION-RULES.md for rules and standards/ for hard rules and opinions.PATTERNS-CATALOG.md to find established agent implementation patterns.agent-docs/ directory contains references for specific tools like Claude Code, Codex CLI, and OpenCode.The agnix-lsp server provides real-time validation and developer productivity features for agent configuration files:
didChange), on file open, and on file save.agnix validation rules, including project-level cross-file rules (e.g., AGM-006, XP-004/005/006, VER-001).name, version, and model.agnix is a linter for agent configurations, supporting 443 rules across 40 categories. It validates a wide range of files used by various AI agent tools, including:
SKILL.md (34 rules)settings.json (Hooks), CLAUDE.md/CLAUDE.local.md (Memory), .claude/output-styles/*.md (Output Styles), and .claude/settings.json (Settings)AGENTS.md (Cross-Tool), agents/*.md (Agents).github/copilot-instructions.md, .github/hooks/hooks.json, and related files.cursorrules, .cursor/rules/*.mdc, .cursor/hooks.json, and .cursor/environment.json.clinerules, .clinerules/*.md, and .clinerules/*.txtopencode.json and opencode.jsonc.windsurf/rules/*.md, .windsurf/workflows/*.md, and .windsurfrules.kiro/steering/*.md, .kiro/agents/**/*.{json,md}, .kiro/hooks/*.kiro.hook, and .kiro/settings/*.jsonThe agnix Knowledge Base serves as the canonical documentation for validation rules, standards, and research sources used by the linter. Use the following files to find specific information:
agentsys.HARD-RULES and OPINIONS organized by topic.Agnix categorizes linting detections into three certainty levels, which determine how they are reported and whether they can be automatically fixed:
AI-generated code poses risks like filesystem access, network exfiltration, and resource exhaustion. Use isolation technologies based on your required security level:
Recommended Architecture: Use a Sandbox Controller to orchestrate and validate execution within an isolated environment that has no network by default, a read-only filesystem, and strict resource limits.
Agnix validates Agent Skill files (typically YAML frontmatter followed by a body) to ensure they adhere to the agentskills.io specification. Key validation checks include:
--- (YAML frontmatter exists).name field is present and not empty.name format. It should be a bare skill name or follow the <plugin>:<skill-name> pattern using kebab-case segments.If AS-001 fails, validation stops because the frontmatter cannot be parsed.
// Example of how AS-001 and AS-002 are checked internally
if !content.starts_with("---") {
diagnostics.push(Diagnostic::error(path, 1, 0, "AS-001", "Missing YAML frontmatter".to_string()));
return diagnostics;
}
if frontmatter.name.is_empty() {
diagnostics.push(Diagnostic::error(path, 2, 0, "AS-002", "Missing required field: name".to_string()));
}Agnix provides deep technical context for specific agentic platforms and protocols. Use these resources to understand the constraints and best practices for each:
standards/claude-code-HARD-RULES.md for technical specifications and standards/claude-code-OPINIONS.md for usage patterns.standards/mcp-HARD-RULES.md for protocol compliance and standards/mcp-OPINIONS.md for tool design patterns.standards/multi-platform-HARD-RULES.md for the compatibility matrix and standards/multi-platform-OPINIONS.md for cross-platform tips.standards/prompt-engineering-HARD-RULES.md for research-backed requirements.Codex CLI employs OS-level sandboxing to ensure safety, especially when running in full-auto mode.
iptables firewall that denies all egress except for necessary API calls, providing full filesystem isolation.Full-Auto Mode Safety: In this mode, all commands are executed with network-disabled, confined to the working directory, and allowed access only to temporary storage.
Both parties must respect the negotiated protocol version and only use capabilities successfully negotiated during initialization. If a server declares a capability, it MUST implement the associated methods.
| Category | Capability | Required Implementation |
|---|---|---|
| Server | tools | tools/list, tools/call |
| Server | resources | resources/list, resources/read |
| Server | prompts | prompts/list, prompts/get |
| Server | logging | Accept log messages |
| Client | roots | Provide filesystem roots |
| Client | sampling | Handle LLM sampling requests |
| Client | elicitation | Handle user input requests |
Reference Skills are used to provide background knowledge, conventions, or context that should be loaded automatically when relevant. They act as guardrails to reduce back-and-forth by providing the agent with established patterns (e.g., API design principles, folder structures, or coding standards).
Pattern: Define a skill with a name and description that outlines the conventions to follow.
---
name: api-conventions
description: REST API design conventions for this codebase. Apply when working with API endpoints.
---
## API Design Principles
### URL Structure
- Resources: Plural nouns (`/users`, not `/user`)
- Nesting: Max 2 levels (`/users/:id/posts/:id`)
- Actions: POST to collection, PUT to item
### Response Format
```json
{
"data": { /* response payload */ },
"meta": {
"page": 1,
"total": 100
}
}