repo-standards
The standard itself lives in
itsryanarmani/scripts/repo-standards.md.
Read it once. Do not restate it here and do not paraphrase it into a README.
This skill is the procedure for satisfying it, and the parts of the job no
program can finish.
Its rule, so you know what you are aiming at:
One sentence. One command. One screen. Nothing in it that is not true.
When to use this
- A repo is going public.
- A README is stale, thin, or was written by an agent in a hurry.
- You are rolling the standard across more than one repo.
- Someone asks why a repo has no license, no topics, or a grey link preview.
One repo, in order
Do not reorder these. Steps 1 and 2 decide everything after them, and doing them last means rewriting the rest.
1. Find out what the repo actually is
Read the code, not the old README. An agent that writes the pitch from the old README launders whatever was wrong into the new one.
Then pick the kind: cli, library, app, collection, or infrastructure.
The kind decides the section deltas and the images, so getting it wrong wastes
the rest of the work.
2. Write the one sentence
Under 120 characters. What it does, and for whom. This sentence is the README's pitch and the About panel's description, unchanged in both.
Write it before anything else. If you cannot write it, the repo does more than one thing, and no README will hide that.
3. Check the current state
repo-standards readme .
Fix what it reports before you add anything new. Most repos fail on shape, not on content, and shape is cheap.
4. Get the images
This is the step that gets skipped, and it is the one a reader notices. See Images below.
5. Write the README
Start from the matching template in
itsryanarmani/scripts/repo-standards-templates/. Fill every __PLACEHOLDER__.
Delete the instruction comment at the top first, so you cannot ship it.
6. Verify every command in it
Run them. All of them, in a clean directory, as a stranger would.
This is the rule the checker cannot enforce and the one that matters most. A quick start that works only because your machine already has the service running is the most common defect in this fleet's READMEs, and it is invisible to everyone who could have caught it.
7. Set the About panel
gh repo edit itsryanarmani/<repo> \
--description "<the same sentence>" \
--homepage "https://<live url>" \
--add-topic <topic> --add-topic <topic> --add-topic <topic> --add-topic <topic>
Four to twelve topics. On a repo with no stars, topics are the only discovery surface GitHub gives you, and most public repos in this fleet had none.
Topic names on a private repo are public. Do not name an unshipped product.
8. The license
Every repo, public or private. GitHub cannot serve a default one, because a
license has to travel with the clone. Everything else in the community health
set comes from itsryanarmani/.github
and must not be copied into the repo.
9. The social preview
See The social preview. It ends in a browser. Leave it last so it does not block the rest.
Images
A generated banner is decoration. A screenshot of the product doing its job is evidence. Spend the effort on the second one.
An app
Capture the real interface with agent-browser. Run it headed when a login,
a passkey prompt, or a one-time code stands between you and the screen you
want. Headless strands you: the agent tells you to click something in a window
that was never drawn, and nothing errors.
Capture the state that proves the product works, not the empty state. An empty dashboard is a screenshot of nothing.
Log into a seeded or demo account, not one holding real customer data. This
step runs after pre-public-repo-audit in the pipeline, so nothing it commits
gets swept by that skill's PII/secret sweeps. A screenshot of a real logged-in
account bakes emails, names, internal hostnames or keys into a committed,
public image before anyone scans for them. If the only account available holds
real data, redact the frame before committing, or run pre-public-repo-audit's
PII sweep again over the new image.
A CLI
Capture the real terminal, running the command people actually run, with its real output. Not a mock, not a hand-written transcript. A recorded terminal beats a still image, and both beat a logo.
The same PII/secret risk from the app section applies here: this step runs
after pre-public-repo-audit, so nothing sweeps a committed capture. A real
terminal's output can carry an absolute laptop path, an internal hostname, or
an env var the command echoed back. Redact the frame before committing, or run
pre-public-repo-audit's PII sweep again over the new image.
A library
No screenshots. The code example above the fold is the image.
A banner, when you need one
wavespeed run <model> --input prompt="..." generates one. It is identity, not
proof, so keep it plain and do not let it make a claim the software does not
support. Never generate a picture of the product interface: an image model
garbles text and UI, and a fake screenshot of your own app is the one image
that destroys a reader's trust completely.
Where they go
assets/, committed, linked relatively. Not a github.com/user-attachments
URL. Attachments serve anonymous readers today and are not a git object, so
nothing promises they still resolve next year. Attachments are for pull request
proof. The repo is for the README.
Under 500 KB each. Alt text on every one, describing the image rather than the project.
Serve a hero image in both colour schemes or it vanishes for half the readers:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/hero-dark.png"/>
<img src="assets/hero-light.png" alt="Search results, ranked by score" width="900"/>
</picture>
The social preview
The 1280x640 card GitHub serves when the URL is pasted into Slack, X, LinkedIn or Discord. Without one, the preview is a grey card with an avatar on it.
Read the current state:
gh api graphql -f query='{repository(owner:"itsryanarmani",name:"skills"){
openGraphImageUrl usesCustomOpenGraphImage }}'
There is no API that sets it. GraphQL exposes the field for reading only,
and there is no REST endpoint. The website upload paths that circulate in
scripts and Actions (/upload/policies/repository-images) are browser session
endpoints: a gh token sent to them comes back logged_in=no with a 404 or a
422. Anything that claims to automate this is driving a browser.
So:
- Generate or export the image at 1280x640.
- Commit it to
assets/og.png. That copy is the source of truth and survives the next step being skipped. - Upload it in the browser, under Settings, Social preview.
Skip this entirely on private repos. GitHub does not serve a private repo's card to the places a preview is read, so the upload cannot reach the audience it exists for.
Translations
Public repos only, into docs/translations/<iso-639-1>.md, produced by
private-repo-0218 rather than by hand or a one-off script per repo.
Every translated file starts with the commit it was made from:
<!-- translated-from: 4d8c7a6 -->
Without that line nobody can tell a current translation from one describing a version you deleted. A stale translation is worse than none, because the reader cannot tell which they are holding.
Many repos at once
One repo at a time is the wrong shape for a fleet. Batch it.
- Measure first.
standards-coverage --missing readmenames the repos that need work. Do not start from a list you assembled by hand. - Group by kind. All the CLIs together, all the apps together. The judgement about what makes a good CLI README is the expensive part, and it transfers across a group. It does not transfer from a CLI to an app.
- One issue and one pull request per repo. The size cap is per pull request and a README rewrite plus images is not small. A single pull request touching nine repos cannot be reviewed and cannot be reverted.
- Delegate the writing, keep the judgement. A worker can fill a template, run the checker, and fix what it reports. Deciding whether the sentence is true, and whether the screenshot shows the product working, stays with you.
- Judge a delegated job on its diff, never on its exit code. Workers in this roster have exited zero having written nothing.
- Do the browser steps in one pass at the end, once every image is committed. Batching them is the difference between one browser session and thirty.
Branch protection, when a repo goes public
On a solo repo, GitHub's default permissions already stop anyone else merging: write access is required, and only the owner has it. Confirm what you actually have before adding anything:
gh api repos/<owner>/<repo>/collaborators --jq '.[].login'
So protection is not preventing unauthorised merges. It is making the intent explicit and future-proofing for a second collaborator.
Create .github/CODEOWNERS before you rely on it. Unlike CODE_OF_CONDUCT,
CONTRIBUTING and the other community health files, GitHub's org-wide .github
defaults do not cover CODEOWNERS — it has to live in the repo itself. Add
* @<owner> if the file is not already there.
CODEOWNERS alone does not gate merges. It requests a review. It only
becomes a gate once a protection rule adds "require review from code owners"
and restricts who can push. Say that in CONTRIBUTING.md rather than implying
the file is enough on its own.
Set protection with a JSON body, not flags. Nested objects and real booleans
do not survive -f, which sends "true" as a string and gets rejected:
gh api --method PUT repos/<owner>/<repo>/branches/main/protection \
-H "Accept: application/vnd.github+json" --input protection.json
{
"required_status_checks": { "strict": true, "contexts": ["test"] },
"enforce_admins": false,
"required_pull_request_reviews": {
"required_approving_review_count": 0,
"require_code_owner_reviews": true
},
"restrictions": null,
"required_linear_history": false,
"allow_force_pushes": false,
"allow_deletions": false
}
Set required_approving_review_count: 0 on a solo repo. Requiring one approval
locks the owner out of merging their own work without a second account.
allow_force_pushes: false blocks admins too. enforce_admins: false lets
an admin bypass required reviews and status checks. It does not touch the
force-push restriction. The owner gets a real GH006: Cannot force-push to this branch from GitHub. To rewrite history once, PUT the protection with
allow_force_pushes: true, push, then PUT it back. Do not leave it open.
Branch protection and rulesets are unavailable on private repos on GitHub Free. The API returns 403. Public repos on the same account can be gated today.
Scrubbing something from public history
When a commit message, a file, or a reference has to leave history that is already pushed:
git-filter-repo --force --message-callback '<python>' --blob-callback '<python>'rewrites messages and content in one pass. It removes theoriginremote as a safety measure. Re-add it afterwards.Every downstream SHA changes, including on branches you did not touch. Any branch or pull request based on the old history shows as diverged. Expect to recreate them rather than fast-forward.
The force-push is where branch protection and local git safety hooks both gate. A git-safety hook may require a person to run the push, by design.
A PR description is not in git history. GitHub stores it separately, so rewriting commits does not touch it. Sweep the working tree,
git log --all --grep, and every open, closed and merged pull request body. Edit one with:gh api --method PATCH repos/<owner>/<repo>/pulls/<n> -f body="..."
The traps, each of which cost a round trip
- A shields.io badge on a private repo renders
repo not found. It does not fail, it renders a grey badge that reads as a dead project. Shields will not accept a token, and a token in a badge URL is a leaked token. Private repos take static badges or none. community/profilenever reports a security policy. There is nosecuritykey in itsfilesobject, inherited or local, while/security/policyserves the file correctly. Anything built on that endpoint reports the whole fleet as having no policy, forever.- The
.githubdefaults repo must be public. A private one inherits to nothing, silently. - A repo's own file beats the default, and for issue templates the override is
total. Any local
.github/ISSUE_TEMPLATEcontent makes GitHub ignore the defaults rather than merge them. - Run the humanizer before you ship a README. Bold inline-header bullets and em dashes doing a comma's job are what a technical reader notices first on a project's front door.