A Claude Code skill that lints AI agent context files.
Your CLAUDE.md, AGENTS.md, or .cursorrules might be making your agent worse. Research shows that most context files reduce task success rates while increasing costs by 20%+.
agentlint checks your file against 10 rules derived from that research and tells you what to fix.
Based on "Evaluating AGENTS.md" (Gloaguen et al.), which tested context files across multiple coding agents and benchmarks. Verbose context files hurt performance. Only minimal, non-obvious constraints help.
See FINDINGS.md for the full breakdown.
mkdir -p ~/.claude/skills/agentlint
curl -o ~/.claude/skills/agentlint/SKILL.md \
https://raw.githubusercontent.com/danmartuszewski/agentlint/main/.claude/skills/agentlint/SKILL.md# From your project root
mkdir -p .claude/skills/agentlint
curl -o .claude/skills/agentlint/SKILL.md \
https://raw.githubusercontent.com/danmartuszewski/agentlint/main/.claude/skills/agentlint/SKILL.mdIn Claude Code, run:
/agentlint
It will:
- Find your context file (CLAUDE.md, AGENTS.md, .cursorrules, etc.)
- Check it against the 10 rules below
- Report issues with severity and specific fixes
- Offer to rewrite the file
| # | Rule | Severity | Why |
|---|---|---|---|
| 1 | No codebase overviews | HIGH | Agents don't find files faster with them |
| 2 | No redundancy with existing docs | HIGH | Duplicated info actively hurts performance |
| 3 | Minimize requirements | HIGH | Every extra line increases cost without improving results |
| 4 | Specify non-obvious tooling | MEDIUM | Agents follow tool instructions with 1.6-2.5x higher fidelity |
| 5 | Document non-obvious constraints | MEDIUM | Only include what agents can't discover alone |
| 6 | No exploration guidance | MEDIUM | Agents explore fine on their own |
| 7 | No generic coding guidelines | MEDIUM | LLMs already know best practices |
| 8 | Prefer imperative over descriptive | LOW | Direct commands over narrative explanations |
| 9 | Keep it short | LOW | Target under 800 words |
| 10 | Never auto-generate the whole file | HIGH | LLM-generated files consistently decrease performance |
See EXAMPLE.md for a real-world report that cut an AGENTS.md from 2,202 to 268 words (88% reduction).
Doesn't using agentlint violate Rule 10?
No. Rule 10 forbids auto-generating the whole file from scratch — that's the pattern the research found consistently hurts performance. agentlint does the opposite: it audits and trims a file you wrote, stripping out the bloat that LLM-generated files are full of. The rule itself says to "use AI to help edit or trim," which is exactly what this does. If agentlint had to write your CLAUDE.md from nothing, that would violate Rule 10 — which is why it doesn't. When no file exists, it interviews you for the non-obvious constraints worth documenting rather than generating content for you.
Include only what agents cannot discover on their own. Everything else is noise.
MIT