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).
Include only what agents cannot discover on their own. Everything else is noise.
MIT