agentlint-dev 0.1.0

Lint, score, and optimize AI agent configuration files (CLAUDE.md, AGENTS.md, Cursor rules)

agentlint

Lint, score, and optimize your AI agent configuration files.

agentlint analyzes CLAUDE.md, AGENTS.md, Cursor rules, and other AI agent configs — and tells you exactly what's wrong and how to fix it.

Install

pip install agentlint

Usage

# Lint a file and show issues
agentlint lint CLAUDE.md

# Score your config from 0-100
agentlint score CLAUDE.md

# Generate an optimized version
agentlint optimize CLAUDE.md          # saves to CLAUDE.optimized.md
agentlint optimize CLAUDE.md --ai     # uses Claude API for smarter suggestions

# Show diff of what optimize would change
agentlint diff CLAUDE.md

# Scan entire directory for all config files
agentlint scan .

Lint Rules

Code	Severity	Description
TOO_LONG	❌ Error	File exceeds 80 lines — Claude starts ignoring instructions
TOKEN_WASTE	⚠️ Warning	Personality instructions waste tokens with little effect
DUPLICATE_RULE	⚠️ Warning	Same instruction repeated more than once
CONTRADICTION	❌ Error	Conflicting instructions cause unpredictable behavior
MISSING_COMMANDS	❌ Error	No shell commands defined — agent can't verify its work
MISSING_STACK	❌ Error	No tech stack defined — agent may make wrong assumptions
AT_MENTION_ABUSE	⚠️ Warning	Excessive @file refs embed large files every session
NO_VERIFY_STEP	❌ Error	No instructions for verifying changes work
VAGUE_INSTRUCTION	⚠️ Warning	Instruction too vague to be reliably actionable
BLOAT_DETECTED	⚠️ Warning	Lengthy procedures belong in skill files, not base config
MISSING_NEVER	⚠️ Warning	No prohibition rules — negative constraints are highly effective
INSTRUCTION_LIMIT	⚠️ Warning	Estimated 150+ instructions — models lose track

Scoring

Category	Points	What it measures
Length & Density	25	File size, no token waste, no duplicates
Specificity	25	Concrete rules, no vague/contradicting instructions
Structure	25	Headers, bullets, code blocks, no bloat
Completeness	25	Stack, commands, verify step, never rules

License

MIT