Orviqa

README grader: score your README

Name a public GitHub repository or paste a README. You get a score from 0 to 100 on a published rubric, the fixes worth the most points first, and a comparison against 2,069 repositories we analysed for the README Benchmark. No signup, and the whole result is on the page.

Paste a URL or type owner/repository.

How the score works

The score is a weighted checklist. Each category below is scored from 0 to 100 by the checks it contains, and the overall score is the categories combined by weight. Every check reads one feature our extractor detects in the markdown, so the same README always gets the same score and every point can be traced to the check that gave it.

README rubric: categories, weights and checks
CategoryWeightChecks (points within the category)
Value proposition and clarity20%
  • Says what the project is within the first 200 characters (40)
  • The opening sentence is a real explanation (eight words or more) (20)
  • Lists features or explains why it exists (20)
  • Shows the project: a screenshot, diagram or recording (20)
Installation and setup20%
  • Has installation instructions (60)
  • States requirements or prerequisites (20)
  • Contains at least one code block (20)
Usage examples15%
  • Has a quick start or usage section (50)
  • Has an examples section or links to examples (30)
  • Has two or more code blocks (20)
Documentation structure15%
  • Organised under three or more section headings (35)
  • Uses headings, with at most one top-level heading (15)
  • Links to fuller documentation (35)
  • Explains how it works or answers common questions (15)
Target audience and use cases10%
  • Says who it is for or what it is used for (80)
  • States the project status or stability (20)
Contribution guidelines10%
  • Explains how to contribute (60)
  • States the licence in the README (25)
  • Shares a roadmap or what is planned (15)
Calls to action and project links10%
  • Links to a place to ask questions or talk (40)
  • Says where to get help (30)
  • Links to a live demo, playground or website (30)

One check gives partial credit: the opening sentence earns all 40 points within the first 200 characters, 24 within 400 and 10 within 900. Every other check is met or not.

What the score is, and what it is not

It is a heuristic. The weights are our judgement about what a first-time reader needs, written down so you can disagree with them. Nobody has shown that a README scoring 80 gets more users than one scoring 60, and we do not claim it.

The measured number is the comparison beside it: a count against a fixed thirteen-item checklist, and where that count sits among 2,069 real repositories. When the result says a README is more complete than 62% of them, that figure was computed the same way for both sides of the comparison. Below the score, six areas are also rated against the benchmark, with the evidence for each rating.

No language model is involved at any point, which is also why this is free and why two runs over an unchanged README give the same answer.

Limits worth knowing

  • Detection is pattern-based and English-only. An unusually phrased section can be missed.
  • It reads the README, not the repository. A project with excellent docs elsewhere and a thin README will grade poorly, which is arguably the correct answer for a reader who only sees the front page.
  • By URL, public repositories only. Private ones are invisible to the tool, but you can paste a private README instead.
  • The benchmark is observational. A missing element is an absence, not a diagnosis. See the full limitations.

README questions

What makes a good GitHub README?

It answers the questions a first-time reader has, in the order they have them: what is this, is it for me, how do I install it, what does using it look like, and where do I go next. The first of those has to be answered in the first screen, before badges and logos.

In the 2,069 repositories we measured, about six in ten have installation instructions, about a third state their licence in the README, and around nine in ten never say who the project is for.

How is the README score calculated?

Seven categories, each with a fixed weight, each made of a few checks worth fixed points. Every check reads one feature our pattern-based extractor detects in the markdown, such as an installation section or a link to documentation. The category scores are combined by weight into a number from 0 to 100.

The same README always gets the same score, no language model is involved, and the full rubric is published on this page.

Does a higher score mean my project will get more users?

Not necessarily. The rubric is a judgement about what a first-time reader needs, written down so you can check it. Nobody has shown that a README scoring 80 attracts more users than one scoring 60. The benchmark comparison shown beside the score is measured, but it is observational too: popular projects tend to have these sections, which is not proof that adding them causes growth.

Is the README I paste stored?

No. Pasted markdown is graded in memory and discarded. We record that a grade happened and its score, for counting how the tool is used, but not the text. A pasted result also has no shareable link, because there is nothing stored to link to.

Can it check a private repository?

Not by URL: the tool only reads public repositories, and it reports a private one the same way as one that does not exist. You can paste a private README into the paste tab instead.

Related: how to improve your README · open-source launch planner · a README audit in your coding agent (Orviqa Lite) · the benchmark behind this tool · what a README has to do in ten seconds · promoting an open-source project