The README standard

GitHub scores every public repository against a community profile: a list of standard files, and a health percentage counting how many are present. It answers one narrow question, which is whether the files exist. It says nothing about whether the README is any use.

The checklist, and the current score

Numbers below come from the community profile of the repositories under github.com/nerln. Synced on 3 September 2026, across 26 public repositories.

Item	Repositories with it
Description	26 of 26
README	26 of 26
Licence	24 of 26
Contributing guide	3 of 26
Code of conduct	2 of 26
Pull request template	2 of 26
Issue templates	0 of 26

The highest scores: molo at 100, banchina at 100. Most of the rest sit at what a README, a licence and a description add up to.

The rest of the metadata: seventeen MIT, five GPL-3.0, two without a licence, two Apache-2.0. 18 of 26 carry topics; porto, placa, vesuvius-ladder, paratia, boa, dogana, capitaneria, faro have none. 16 declare a homepage.

What the score cannot see

A repository can pass every check and still leave a reader guessing. The questions a README has to answer are different ones: what does this do, what does it refuse to do, can I run it in the next five minutes, and is there a number I can verify myself.

The house rule

What a tool does not do gets a heading of its own. When a claim can be checked, the check ships with it.

That heading is in the real files. molo has “What it will not do” and states that there is no circumvention code in the repository, no CDM and no keys, so an encrypted stream fails because the code cannot do it. rada has “What it does not do” and lists that it never kills a running job, that work which never becomes a Bash command is invisible to it, and that it has only been run on macOS on Apple Silicon. argano uses molo’s heading, and says it will not re-encode anything to make a file play. varo says it has no servers, no databases and no build system of its own, and that its auditor reads and never writes.

Limits get a second heading when they are about what has not been done yet. molo says its builds are unsigned, and that the Windows executable and the Android APK compile in CI with nobody having run them on real hardware. claude-codex-bridge keeps a “Known limitations” section for the same reason.

The checkable claims ship as tests, and the count goes next to the claim: 29 checks in varo, 70 in rada, 138 in plancia. rada also publishes the measurement of prompt injection against its judge: of six styles of attack, one worked. A verdict there is worth at most three points, against an age that earns one every thirty seconds and expires after three minutes, so a successful injection buys ninety seconds of queue jumping.

The order I write to

molo, rada and varo each depart from it. molo puts its refusals before Install and heads no Tests or Licence section, rada puts its refusals after Install, and varo heads its tests Checks.

1. Name, then one line in the words somebody would use to ask for the tool.
2. Why this exists. The concrete situation that produced it, and the projects that already solve part of the problem. molo names five and tells Android-only users to install Seal instead.
3. What it does. One capability per paragraph, described as behaviour.
4. What it does not do. Refusals and hard limits, separated from each other.
5. Install. Copy-pasteable, with the unbundled dependencies named.
6. Using it. The few commands that cover most of the work.
7. How it works. File layout, one line each, plus the decisions a reader would otherwise reverse engineer.
8. Known limitations. What has not been run, signed, or tested anywhere but one machine.
9. Tests. The command, the count, and what they cover.
10. Licence.

Template

# name

One line saying what it is.

## Why this exists

The situation that produced it. Name the projects that already solve
part of the problem, and say plainly when one of them is the better
choice for a given reader.

## What it does

One capability per paragraph. Describe behaviour.

## What it does not do

The refusals and the limits. Separate the things that are choices
from the things the code cannot do at all.

## Install

Commands that can be pasted. Name the dependencies that are not
bundled and say what happens without them.

## Using it

The three or four commands that cover most of the work.

## How it works

The file layout, one line each, and the decisions a reader would
otherwise have to reverse engineer.

## Known limitations

What has not been run, what has not been signed, what has been tested
on one machine only.

## Tests

The command, the count, and what they cover. If a test exists because
it caught a real defect, say so.

## Licence