🧬 AgentLinter

ESLint for AI Agents — Score, diagnose, and auto-fix your entire agent workspace.
Free & open source. Always will be.

Website · Quick Start · Scoring · Comparison · How it Works

---

Why AgentLinter?

Your AI agent is only as good as its config files. A vague CLAUDE.md produces vague results. A leaked API key becomes a vulnerability. Contradictions across files cause unpredictable behavior.

"Be specific: 'Use 2-space indentation' is better than 'Format code properly.'" — Anthropic, CLAUDE.md Best Practices

AgentLinter treats your agent config as code — scanning, scoring, and fixing it with the same rigor you'd apply to source code.

The problems it solves

Problem	Impact	AgentLinter
🔇 Vague instructions fail silently	"Be helpful" gives zero guidance	Detects ambiguity, suggests specifics
🔑 Secrets in plain text	API keys committed to repos	Scans for 20+ secret patterns
🔀 Multi-file drift	SOUL.md contradicts CLAUDE.md	Cross-file consistency checks
📉 No quality baseline	Can't measure improvement	0–100 score across 8 dimensions
🏗️ Missing essentials	No error recovery, no boundaries	Completeness checklist with auto-fix
⚙️ Insecure runtime config	Gateway exposed to network	Runtime config security checks
🛠️ Dangerous skills	`curl	bash` in skill files
🌐 Non-English config files	2.5x token waste, interpretation errors	Detects non-English content, suggests translation

---

Quick Start

npx agentlinter

That's it. Free, open source, forever. No config. No API key. No signup. No paywall. Runs in seconds.

🔍 AgentLinter v0.2.0
📁 Scanning workspace: .claude/ + root
   Found 5 files: CLAUDE.md, SOUL.md, USER.md, TOOLS.md, SECURITY.md

  Workspace Score ........ 76/100  (B+)
  ├─ Structure     ████████░░  80
  ├─ Clarity       ███████░░░  70
  ├─ Completeness  ██████░░░░  60
  ├─ Security      █████████░  90
  ├─ Consistency   ██████░░░░  60
  ├─ Memory        ████████░░  80
  ├─ Runtime Cfg   █████████░  88
  └─ Skill Safety  █████████░  92

  2 critical(s) · 3 warning(s)

  🔴 CRITICAL  TOOLS.md:14 — Secret: API key pattern "sk-proj-..."
  🔴 CRITICAL  SOUL.md ↔ CLAUDE.md — Conflicting persona definition
  ⚠️  WARN  CLAUDE.md:28 — Vague: "be helpful" → be specific
  ⚠️  WARN  No error recovery strategy defined
  ⚠️  WARN  2 cross-file references broken

  💡 3 issues with suggested fixes. See report for details.
  📊 Report → agentlinter.com/r/a3f8k2

Commands

# Score your workspace
npx agentlinter

# Auto-fix safe issues
npx agentlinter --fix

# Bootstrap a new workspace from template
npx agentlinter init --template coding

# Share your score
npx agentlinter share

---

Automatic Mode Detection

AgentLinter automatically detects whether you're running in Project Mode (Claude Code) or Agent Mode (OpenClaw/Moltbot/Clawdbot) and adjusts recommendations accordingly.

Mode	Detected When	Rules Applied
Project Mode	Only CLAUDE.md present	Project-scoped rules (no memory/user context requirements)
Agent Mode	AGENTS.md, openclaw.json, moltbot.json, or clawdbot.json present	Full rules (memory strategy, user context, handoff protocol)

This means:

• Claude Code projects won't get recommendations for USER.md, memory strategies, or session handoff — those are OpenClaw patterns
• OpenClaw agents get the full rule set for persistent, multi-session agents

No configuration needed — it just works.

---

How it Works

1. 🔍 Scan

Discovers every .md file in your agent workspace — CLAUDE.md, SOUL.md, USER.md, TOOLS.md, SECURITY.md, .claude/rules/, skill files, and more.

Supports Claude Code, OpenClaw, Moltbot, Cursor, Windsurf, and any workspace following the Agent Skills open standard.

2. 📊 Score

Evaluates across eight dimensions, each scored 0–100. Every rule is documented and derived from Anthropic's official best practices plus patterns from high-performing agent workspaces.

3. ⚡ Fix

Every issue comes with a prescription. Most are auto-fixable with --fix:

• Secrets get flagged for immediate rotation
• Vague instructions get specific rewrites
• Missing sections get scaffolded
• Cross-file contradictions get highlighted with resolution suggestions

---

Eight Scoring Dimensions

Each dimension checks specific, documented rules:

Structure — 12%

File organization, naming conventions, section hierarchy.

Rule	Severity	Example
Required files present	Critical	Missing TOOLS.md — referenced in CLAUDE.md:12
Section separation	Warning	CLAUDE.md has 200+ lines with no headers
Naming conventions	Info	Use CLAUDE.md, not claude.md
Frontmatter format	Info	SKILL.md missing description field

Clarity — 20%

Instruction quality — can an AI agent unambiguously follow these?

Rule	Severity	Example
Naked conditionals	Critical	"If appropriate" — what's the criteria?
Compound instructions	Warning	Line has 4 instructions — split them
Ambiguous pronouns	Warning	"Update it" — update what?
Missing priorities	Warning	No P0/P1/P2 signals — which tasks first?
Vague language	Warning	"be helpful" → specify: response length, tone, format

Completeness — 12%

Does the workspace cover all essential aspects?

Rule	Severity	Example
Identity/persona defined	Warning	No SOUL.md or persona section found
Tool documentation	Warning	6 tools referenced but undocumented
Boundaries & constraints	Warning	No safety boundaries defined
Error recovery strategy	Warning	No escalation or fallback path

Security — 15%

Protecting your agent and your data.

Rule	Severity	Example
Secret detection	Critical	API key pattern "sk-proj-..." in TOOLS.md:14
Token patterns	Critical	GitHub token "ghp_..." exposed
Injection defense	Warning	No prompt injection defense instructions
Permission boundaries	Warning	No external action restrictions

Consistency — 8%

Cross-file coherence across the entire workspace.

Rule	Severity	Example
Persona alignment	Critical	SOUL.md persona ≠ CLAUDE.md persona
Permission conflicts	Critical	CLAUDE.md allows X, SECURITY.md forbids X
Broken references	Warning	CLAUDE.md:12 references TOOLS.md — file not found
Language mixing	Info	Mixed ko/en in same section

Memory — 10%

Session handoff and knowledge persistence.

Rule	Severity	Example
Session handoff protocol	Warning	No handoff protocol — agent loses context between sessions
File-based persistence	Warning	No daily notes or progress files
Task state tracking	Info	Consider adding progress.md
Learning loop	Info	No knowledge distillation strategy

Runtime Config — 13%

OpenClaw/Gateway configuration security.

Rule	Severity	Example
Gateway bind	Critical	Gateway bind "0.0.0.0" — exposes agent to network
Auth mode enabled	Critical	No auth configured — agent exposed
Token strength	Warning	Token < 32 chars — use stronger token
DM/group policy	Warning	No DM policy — consider restricting
Plaintext secrets	Critical	API key in config file

Skill Safety — 10%

Dangerous patterns in skill files.

Rule	Severity	Example
Dangerous shell commands	Critical	Skill contains: rm -rf /
Curl pipe bash	Critical	Skill contains: curl ... | bash
Sensitive path access	Warning	Skill accesses ~/.ssh
Data exfiltration	Warning	Skill sends data to external URL
Prompt injection vectors	Warning	Skill vulnerable to injection

---

Starter Templates

Bootstrap a new workspace with best practices built in:

npx agentlinter init --template <type>

Template	Files Created	Best For
personal	CLAUDE.md, SOUL.md, USER.md	Personal AI assistant
coding	CLAUDE.md, TOOLS.md, SECURITY.md	Coding agents (Claude Code, Cursor)
team	CLAUDE.md, TOOLS.md, SECURITY.md, .agentlinterrc	Team agent workspace
chatbot	CLAUDE.md, SOUL.md, SECURITY.md	Customer-facing chatbots

---

Custom Rules

Enforce your team's standards with .agentlinterrc:

{
  "extends": "agentlinter:recommended",
  "rules": {
    "require-files": ["CLAUDE.md", "SECURITY.md"],
    "max-file-length": 300,
    "require-section": ["## Boundaries", "## Tools"],
    "no-vague-language": "error",
    "require-injection-defense": "error"
  },
  "ignore": ["drafts/"]
}

---

Score Reports & Sharing

Every run generates a web report with:

• Tier grade: S → A+ → A → B+ → B → C
• Category breakdown: Visual bars for each dimension
• Prescriptions: Exact issues with auto-fix markers
• Percentile ranking: Where you stand among all agents
• Progress tracking: Watch your score improve over time

Share on X

My AI agent scored 87/100 on @AgentLinter 🔍

Structure: 80 | Clarity: 90 | Security: 95

How sharp is YOUR agent?
→ agentlinter.com

---

VS Anthropic's Official Tools

Anthropic provides CLAUDE.md memory and skills — the building blocks for agent configuration. AgentLinter tells you if you're using them well.

Feature	Claude Code (Anthropic)	AgentLinter
Scoring	Basic via /init	✅ 8-category (0-100)
Scope	Single CLAUDE.md	✅ Full workspace
Cross-file checks	—	✅ Contradiction detection
Secret scanning	—	✅ 20+ patterns
Runtime config audit	—	✅ Gateway/auth checks
Skill safety scan	—	✅ Dangerous pattern detection
Auto-fix	Prompting suggestions	✅ One-command --fix
Custom rules	—	✅ .agentlinterrc
CI/CD	—	✅ GitHub Action
Templates	/init	✅ 4 starter templates
Reports	—	✅ Web + Share on X
Frameworks	Claude Code only	✅ CC, OpenClaw, Moltbot, Cursor, Windsurf

Not a replacement — an extension. AgentLinter builds on Anthropic's CLAUDE.md standard and the Agent Skills open standard. Think of it as ESLint for JavaScript — the language gives you the syntax, the linter tells you if your code is good.

---

Self-Evolving Rules

AgentLinter gets smarter with every run:

Lint → Share → More Users → More Data → Better Rules → ↻

Level	Type	How it works
L1	Auto	Rule weights adjust based on which warnings users fix immediately
L2	Semi	Patterns in top-scoring agents become new rule candidates
L3	Auto	Low-acceptance fixes get A/B tested and replaced
L4	Semi	Starter templates evolve based on what files users add

All data anonymized. Opt-out: --no-telemetry

---

CI/CD Integration

GitHub Action

# .github/workflows/agentlinter.yml
name: AgentLinter
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npx agentlinter
      - run: npx agentlinter --format github

Score changes are posted as PR comments automatically.

---

Supported Frameworks

Framework	Config Files	Status
Claude Code	CLAUDE.md, .claude/rules/, .claude/skills/	✅ Full support
OpenClaw	AGENTS.md, SOUL.md, USER.md, TOOLS.md, openclaw.json	✅ Full support
Moltbot	AGENTS.md, SOUL.md, moltbot.json	✅ Full support
Clawdbot	AGENTS.md, SOUL.md, USER.md, TOOLS.md, clawdbot.json	✅ Full support
Cursor	.cursorrules, .cursor/rules/	✅ Full support
Windsurf	.windsurfrules, .windsurf/rules/	✅ Full support
Any Agent Skills	SKILL.md with frontmatter	✅ Full support

---

Privacy

Local-first by design. All scanning and scoring runs 100% on your machine. Your file contents never leave.

What stays local (always)

• ✅ Your actual file contents (CLAUDE.md, SOUL.md, etc.)
• ✅ System prompts and personal context
• ✅ Security rules and sensitive instructions

What's shared (only when report link is generated)

• 📊 Scores and grades
• 📄 File names (not contents)
• 💬 Diagnostic messages (e.g., "Line 28: vague instruction")

Options

• Use --local flag to skip sharing entirely — zero network calls
• Secrets are auto-masked in reports (API keys show as [REDACTED])
• No telemetry by default

---

Roadmap

• Core scoring engine (8 dimensions)
• Auto-fix with --fix
• Secret scanning (20+ patterns)
• Cross-file consistency checks
• Web reports with sharing
• Runtime config audit
• Skill safety scanning
• GitHub Action marketplace release
• VS Code extension (real-time linting)
• Team dashboard
• Leaderboard & badges

---

Contributing

We welcome contributions! Areas where help is needed:

• New rules — See src/engine/rules/ for the pattern
• Framework support — Add parsers for new agent frameworks
• Templates — Create starter templates for new use cases
• Docs — Improve documentation and examples

git clone https://github.com/seojoonkim/agentlinter
cd agentlinter
npm install
npm run dev

---

License

MIT

---

⭐ Star on GitHub · @simonkim_nft

Built on Anthropic's CLAUDE.md standard · Agent Skills open standard