Grade your repository’s agent file and add a badge

What the grader reads

The grader looks at the root of the repository’s default branch and grades the first of these it finds:

1. CLAUDE.md, the project file Claude Code reads.
2. AGENTS.md, the open file Codex, Cursor and other coding agents read.
3. .cursorrules, the project rules file Cursor reads from the root.
4. SKILL.md, an Agent Skill for Claude.

It reads public repositories only, and only the file itself, from GitHub’s raw file host. A file over 12,000 characters is not graded; paste a shorter version into Grade my file instead. A repository with none of these files gets a link to the agent-file maker, which writes one from your README.

How the grade works

The six scorecard ingredients are read as they apply to an agent file. Each is scored from 0 to 5, and the grade is their total out of 100.

1. Focus. Whether every line tells the agent something it could not work out from the code: the project’s own conventions, pitfalls and decisions. Directory tours, dependency lists and architecture overviews earn nothing.
2. Project facts. What the code does not show: setup and environment quirks, the services it depends on, generated folders, and where the project departs from its framework’s defaults.
3. Rules and limits. Conventions, scope, and what the agent must never do.
4. File conventions. Whether the file takes the shape its tool expects.
5. Commands and examples. The exact build, test, lint and run commands, and short examples of the patterns to follow.
6. Done check. How the agent confirms its work before it finishes.

Focus follows the evidence. A 2026 study found that repository overviews in these files did not help coding agents, and that the files earn their place by recording practices an agent would not otherwise follow (Gloaguen et al.). Anthropic’s own check for CLAUDE.md files trims the same kind of content.

A SKILL.md is read as a skill rather than a project file: whether its description says what it does and when to use it, what it works from, its limits, its format, its steps and how it checks its output.

See the grade at work on 10 real CLAUDE.md files and 8 AGENTS.md files from open-source projects.

The page lists up to three things holding the file back and an improved version in the same format. Parts in [brackets] are details the file did not give; fill them in before you commit it.

The README badge

Every grade page has the badge’s Markdown with a Copy button. Paste it into your README, and the badge shows the latest grade and links to the page.

[![Prompt grade](https://looptypes.com/badge/owner/repo.svg)](https://looptypes.com/grade/owner/repo?utm_source=github&utm_medium=badge&utm_campaign=repo-grade)

• Replace owner/repo with your repository, or copy the Markdown from its grade page.
• The badge reads “prompt grade” and the score, such as 82/100. Its color runs from red below 40 through orange, yellow and green to bright green at 90 and above.
• A repository that has not been graded shows “not graded”. A badge never grades anything on its own.
• After you change the file, grade the repository again and the badge follows. Grading an unchanged file again returns the same grade and uses nothing, unless the way files are graded has changed since; then it is graded afresh.

Questions

Does grading a repository cost anything?

Without an account, it uses the same free daily allowance as the prompt scorecard. With a free account, it counts as one Quick prompt. Grading a file that has not changed since its last grade is free.

Can it grade a private repository?

No. The grader reads only what GitHub serves publicly, and a private or missing repository is simply not found.

What does the grade page show about my repository?

The file’s name, its grade, the breakdown, what holds it back and the improved version. The improved version is written from your public file and nothing else.

Sources

• Gloaguen et al., “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, arXiv, 2026
• Anthropic, “How Claude remembers your project” (Claude Code documentation)
• Anthropic, “Skill authoring best practices”