README.md sucks
Declare what your repo does and how to use it in a structured, yet human-readable schema. Your code repository is an artifact that can receive input and provide output to the outside world. In effect, this means it has an implicit "function signature", and we do ourselves a disservice by attempting to describe these things in prose.
Sample repo.cue file structure
CUE has a very intuitive and descriptive syntax, while also being far more powerful than YAML or JSON. The schema validator and schema itself are implemented in CUE, which is capable of validating the schema of YAML and JSON files. The suggested convention is to start providing a repo.cue/repo.yaml/repo.json file (per your preferred syntax) at the root of your repository alongside your README.md file.
repovet schema validator
Install
brew install nreilingh/tap/repovet
Validate the closest repo.cue/repo.json/repo.yaml file in the working directory
repovet
Validate a specific file
repovet a_specific_file.cue
Print out the schema sample
repovet sample