Context file checker

What this checks

Twelve structural checks. Five apply to any context file, four are specific to AGENTS.md and CLAUDE.md, and three to llms.txt. There is no single vanity score with no breakdown — that is what the GEO scoring category already does, and it is the thing this cluster is positioned against.

Any context file

1. Parses cleanly — no unclosed code fences, which silently swallow everything after them.
2. Has a top-level heading — the first thing a reader needs is what this file is about.
3. Sections present and not duplicated — repeated headings produce contradictory instructions in the same file.
4. Length is sane — reported in lines and estimated tokens, flagged past the point where these files start being diluted.
5. No placeholder content — TODO, TBD and unfilled template brackets left in a file that agents read as fact.

AGENTS.md and CLAUDE.md

6. Contains actionable specifics — real commands and paths, not prose describing them.
7. States explicit boundaries — what must not be touched. The most commonly missing section, and the most expensive to omit.
8. Has verifiable done-criteria — a check the agent can run to know it succeeded.
9. No vague directives — "be careful", "use your best judgement", "where appropriate". Unenforceable by a human and worse than nothing for a machine.

llms.txt

10. Links are well formed and same-origin — third-party links can change after you review them.
11. No instruction-shaped content — the moment the file starts telling readers what to do, it stops being a map and becomes an injection surface.
12. Descriptions present — a bare list of URLs gives an agent no basis for choosing between them.

What a good context file looks like

The pattern that passes is short, specific, and closer to a runbook than to documentation. Commands rather than descriptions of commands. Boundaries stated as boundaries. One check the agent can run to know it is done.

# Campaign workspace

## Where things are
- Brand rules: `/context/brand.md` — read this first
- Approved claims: `/context/claims.md`

## Before you publish anything
- Run the claims check against `/context/claims.md`
- Any health, safety or comparative claim goes to legal review

## Do not
- Do not edit files in `/legal/`
- Do not write pricing. Pricing comes from the commercial team.
- Do not publish without a named human approver on the ticket

## Done means
- Claims check passes, approver named, no `/legal/` file modified

What fails is the file that reads like an onboarding document — three screens of philosophy, a tone-of-voice paragraph, no commands and no boundaries. It passes every human review it is ever given, because nothing in it is wrong. It just contains nothing a machine can act on.

Why context file bloat costs you

The instinct with these files is to add. It reads as thoroughness. The evidence says otherwise, and it is worth knowing before you write your next one.

In February 2026 researchers at ETH Zurich published the first rigorous evaluation of whether repository context files help, testing several coding agents and models across established benchmarks plus a new set of issues drawn from repositories where developers had written and committed their own files. From the abstract: providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average — and that held for both LLM-generated and developer-committed files.

The behavioural explanation is the useful part, and the paper is explicit about it: the lack of improvement is not due to a lack of instruction-following capabilities. The agents did exactly what the files said. Naming a tool was enough to make them reach for it — uv was invoked 1.6 times per task when mentioned, against fewer than 0.01 times when it wasn't.

Related

If the file you just checked raised more questions than it answered, these go deeper: