The problem: nobody keeps them up to date.
Paths get renamed. npm scripts change. Framework patterns go stale. The file that was accurate when you wrote it in September starts giving your agents wrong instructions by December — without a single commit to AGENTS.md.
An ETH Zurich study presented at ICSE 2026 put numbers on this: stale context files reduced agent task success by 2–3% while increasing token costs by over 20%.
agents-lint is a zero-dependency CLI that catches this automatically:
npx agents-lint
It runs five independent checks:
1. Filesystem — every path mentioned in your file is verified to exist
2. npm scripts — every `npm run <script>` is verified against package.json (workspace-aware)
3. Dependencies — deprecated packages (moment, request, tslint) are flagged
4. Framework staleness — Angular NgModules in Angular 14+, ReactDOM.render() in React 19, getInitialProps in Next.js App Router, CommonJS in ESM projects
5. Structure — recommended sections, bloat (>15k chars adds 20% token cost), unresolved TODOs, old year referencesEvery run produces a freshness score (0–100). The real value is adding it to CI with a weekly schedule — because context rot happens even when the file hasn't changed:
schedule:
- cron: '0 9 * * 1' # Every Monday
That weekly schedule is the whole point. Your AGENTS.md can rot without a single commit to it.When multiple agent config files exist (AGENTS.md + CLAUDE.md, etc.), it also cross-checks them for conflicting instructions — e.g. one file says `npm run test`, the other says `npm run test:unit`.
What I found when testing on real repos: absolute home-directory paths that only work on the author's machine, monorepo commands copy-pasted into single-package projects, and framework references to APIs removed two major versions ago. All silently misleading agents on every task.
Landing page: https://giacomo.github.io/agents-lint/ npm: https://www.npmjs.com/package/agents-lint
Would love feedback — especially if you find unexpected issues in your own AGENTS.md.