github-readme

GitHub README writing conventions

This Skill has two sources:

uv、shadcn/ui、Supabase、Astro、Tailwind README paradigms of high-star repositories.
answer-me-with-html 50-plus README commits in one repository, two rounds of slimming down, and changes the maintainer made by hand on the GitHub web UI. The "in practice" notes in parentheses after the rules come from there.

There are only three core points:Speak plainly；Readers understand the first screen in 3 seconds；A README answers only four things。

Below, scripts/、references/、assets/ are all relative to this skill's directory, not the target repository.

Zero, first sort the task

First determine which kind the user wants to do, then follow the corresponding process. If unsure, ask.

Task	When	Process
Write new	There is no README, or the whole thing needs rewriting	Fact list → ask the user for missing facts → write in the order of section three → run the scripts → independent verification
Update	The functionality changed, and parts of the README are outdated	Read the README and `git log -p -- README.md` → compare against the code, mark each claim as "still true / outdated / cannot find" → edit in place, delete what is outdated → change both languages together → run the scripts
Slim down	The README exceeds 350 lines, or the user says it is too long	List the line count of each section → decide per section one whether to keep it or move it out → move it into `docs/`(both languages) and leave a summary and deep link → run the scripts and confirm all anchors are still valid
Review	The user asks you to check the README	Fact list + run the scripts + section eight checklist → deliver a report. Do not change files unless the user asks

Edit in place, do not append. Directly rewrite or delete outdated paragraphs; do not add a section of "update notes" after them.
Major change(writing new, or changes exceeding about 1/3 of the whole text) after completion, do one independent verification: hand the references/verification-brief.md prompt to a subagent that did not participate in writing, and fix the blockers and highs it reports. Skip this step for routine small changes.

Fact list

Before writing or changing anything, map each claim you will write to its source:

Claim	Where to check
Installation and usage commands	`package.json` scripts、`Makefile`, the CLI's `--help` output
Defaults and settings	The code that reads this value, not comments or `.env.example`
Runtime version and License	The manifest's `engines` / `requires-python` / `license` fields,`LICENSE` file
Which platforms or agents are supported	Install scripts, tests, CI matrix
Measured numbers	The data file and the command that generates it

Do not write claims whose source cannot be found。
Ask first about things only the user knows: measured numbers, motivation stories, conclusions from comparisons with other projects, screenshots, and videos. If you cannot get an answer, write it as When delivering, give the user the TODO list; the script will also report them as errors.
For external links, only use URLs confirmed to open, and do not concatenate guessed addresses.
Omission check: list every command and setting the user can see, and each one must appear at least once in the README or in the docs/ it links to.

1. The README answers only four things

What it is: a one-sentence definition, plus one verifiable number.
Why use it: comparison chart, measured numbers, and differences from alternatives.
How to install: copy and run.
What it looks like: screenshots, videos, and "you ask → you get" examples.

Put the rest of the content into docs/, such as the full configuration table, command parameters, edge cases, old-version migration notes, and switches only a few people need. Leave in the README's original placea one-sentence summary and a deep link：Defaults and values: [reference](docs/reference.md#settings)。

Length: about 300 lines. If it exceeds 350 lines, do a slimming pass. (In practice: two slimming passes, 388 → 320, 361 → 310.)
Slimming only moves, never deletes. State clearly in the commit where things were moved.
Migration tips are temporary. For breaking changes, "how to uninstall the old plugin" stays in the README only during the transition period, then moves into docs.
Put minority needs next to the opposite feature. For example, put "want it to be less proactive" at the end of the "high-frequency mode" section, with one sentence and a link.

2. Speak plainly

See references/anti-ai-slop.md。

1. Call things what they are

Write the actual behavior of basic features, using everyday engineer vocabulary.
❌ "Adopts a dual-core floating capsule toolbar combined with a 600ms circular charge-loading mechanism to form a first-screen performance protection matrix"
✅ "Cards show only a static cover by default. Preview starts only on click or hover, and at most 6 sandboxes are kept in the background."

2. One sentence says only one thing

A single Chinese sentence should not exceed 25 characters, and English should not exceed 20 words.
❌ "The runtime endpoint is physically isolated under a separate path via strict CSP response headers, and allow-same-origin is resolutely not granted, cutting off access to the host main domain's cookies and session credentials at the root."
✅ "The page runs under a separate /raw/ path and has allow-same-origindisabled. Even if unknown scripts run, they cannot touch the main site's cookies."

3. Use people's actions as the subject

Drag in, open, copy, paste, deploy.
✅ "Supports one-click switching among desktop, tablet, and phone viewports."

4. Motivation should describe real trouble

Motivation comes from the user's own experience. If the user has not described it, first ask, "Why did you make this at the time? Where were you stuck?"
When writing, make it sound like a real person talking about pitfalls they hit, with specific details. The following are tone examples, not content:"The page quality is good, but it is very slow: one page takes one or two minutes, mostly hundreds of lines of CSS that are almost the same every time. The arrows also often point at blank space."
For where to put motivation, see section 3.

5. Write headings as nouns or questions readers would ask

## Background is better than ## Why , and## How it works is better than ## Why it's fast .
Title should be short: the text in parentheses goes into the anchor, so changing the title changes the anchor.

3. Structure and Order

Arrange in the order below. Skip sections you don't have, but keep the order unchanged.

#	Section	Key points
1	Masthead	See "Six Layers of the Header" below
2	Above-the-fold visual	Before/after comparison image → what users will ask → demo video
3	Addressing doubts	`## Why not just X?`、`## How is this different from Y?`
4	Install	See Section 5
5	Example	A "You ask → You get" table, including one counterexample row
6	Features and Settings	One summary paragraph per item + link to docs
7	Background	Motivation story, within 10 lines
8	How it works / Features / Development	Mechanism,`- 关键词: 事实` list, development commands
9	Footer	Community → Star History → License, License always last

Six Layers of the Header

<p align="center"><img src="docs/logo.svg" width="64" height="64" alt="..."></p>
<h1 align="center">Project</h1>
<p align="center"><b>Feature A&nbsp;&nbsp;|&nbsp;&nbsp;Feature B&nbsp;&nbsp;|&nbsp;&nbsp;Feature C</b></p>   <!-- 可选关键词行 -->
<p align="center"><b>是什么 + 解决什么。<br>一个可验证的数字。</b></p>
<p align="center"> 徽章 </p>
<p align="center"><a href="..."><b>Website</b></a> · <a href="#install">Install</a> · ... · <a href="README.zh-CN.md">简体中文</a></p>

Logo: centered, 48 to 64px.
Keyword line: optional, at most 4 items, each a verifiable feature name, e.g. One File, Offline、ASD-STE100。
Tagline: first say what it is and what it solves, then give a verifiable number. For example:「An agent skill. Ask a hard question, get a page you can actually read. The model writes about 1/8 of the tokens.」
Badges: only pick the ones useful to readers, keep the style consistent. See below and assets/badges.md。
Link line: occupy only one line. Put the official website first and in bold, and the language switcher last. In the middle put the 4 to 5 anchors and docs links readers look for most. If the GitHub page width can't fit them, delete items. (In practice: three lines merged into one, Settings and How it works were moved out.)

Badges

Choose based on what readers want to know: version, Stars, which platforms or agents are supported, third-party rankings or recognition. For self-hosted projects, add Docker too.
Unify style、labelColor、color. Consistency of style matters more than quantity. (In practice:style=flat-square&labelColor=16181d&color=2ea44f。）
License is written in the footer's ## License. CI status is for contributors, so leave it on the Actions page. (In practice: removed four badges—License, CI, Node version, zero CDN—since the latter two are already covered in the body.)

Above-the-fold visual

Before/after comparison image first: the same question, on the left the original state, on the right after using the project. It answers both "what it is" and "why use it." (In practice: the maintainer personally moved the comparison image on the webpage to right below the masthead.)
Then put the 2 to 3 sentences users would actually type, then the demo video.
Use GitHub attachments for videos: upload the MP4 in an issue or PR comment, put the https://github.com/user-attachments/assets/... link on its own line, and GitHub will play it inline with sound. Below the video, use <sub> to write the duration and a hint, e.g. "24-second demo. Turn the sound on for the music."
When the repository is installed by cloning the whole thing(skill, plugin, template repos), put videos, GIFs, and benchmark corpora outside git: use attachment links for videos and release downloads for corpora.
When screenshots need both light and dark versions, use <picture>, see the syntax in assets/badges.md。

Addressing doubts

Write the reader's first "why not just use X?" as a question heading, placed before Install. In the body, first acknowledge that X works, then give the gap:「You can. Models write decent HTML now. But most of what they write is not content.」
Differences from similar projects: the README only writes one paragraph, put the full comparison table in docs/compare.md。
Honestly acknowledge the other side's strengths, and write "not tested" for things you haven't tested:「Its diagram tools go further than ours.」、「We did not measure X.」 This actually makes it more credible.

Example table

| You ask | You get | Two columns, each row containing the user's exact words and the concrete output.
Add a counterexample row explaining when it is not triggered:「"How do I show hidden files with ls?" → No page. A one-line question gets a one-line answer.」

Background

Place it after installation and examples, within 10 lines. Only readers who are already interested will see this.
Structure: trigger (a link) → what you tried yourself and where you got stuck → so what this project does.

4. Numbers and benchmarks

Every number comes with conditions: sample size, number of repetitions, how values are taken, model or hardware, environment. For example (3 topics × 3 runs, medians, Claude Sonnet 5.5, a plain Claude Code setup)。
Reproducible: provide the data file and one command, for example node bench/corpus.mjs gives the same numbers every time。
Escalate the methodology step by step: estimate → measured → fixed corpus. After escalating, delete the tables and statements from the old methodology.
The main table only contains robust metrics, such as output tokens and time taken. For unfavorable metrics, write one sentence explaining the reason, then link to the details:「The bill drops less than the writing, about 15% here, because every turn also reads the system prompt.」
Write small samples as one sentence：「about 18× fewer output tokens in a small test」。
Writing style：about add an integer or simple fraction (about 1/8、8× fewer、2.6× faster). Bold the conclusion in the last column of the table.
Expand each number in only one place. The tagline can cite the main number. Elsewhere, use links to point to it.
After re-measuring, search for the old numbers in the README,docs/, the official website, and both the Chinese and English versions, and change them all.

5. Installation section

Write the prerequisites first: runtime and version, and whether a separate install step is needed. For example, "You need Node.js 20 or newer. There is no npm install step.」
One subsection per installation method, with the recommended one first, and the title written as (recommended)。
Collapse manual installationinto <details><summary>Manual install</summary>。
Tools for agents(skill, plugin, MCP server): the first method is a one-sentence prompt that tells the agent to read the INSTALL.md in the repository and install accordingly. The installation logic will change, so only change INSTALL.md, and keep the prompt in the README unchanged. For the writing style, see references/agent-skill.md。
The last sentence of the installation section points to the next step, for example, "No setup is needed. We recommend turning on always-on mode.」

When recommending a feature

write four things in order:

Default state: "It is off by default."
Why it is recommended, in one sentence.
Cost: "Pages pile up; clear them with am clean.」
A command or snippet that can be copied directly.

Snippets in the README that users or agents paste directly are also code: keep them consistent with the source files, and write tests if possible.

6. Bilingual README

First decide the primary audience. For international developer tools:README.md in English,README.zh-CN.md in Chinese. Put the language switch at the end of the link line.
The Chinese version is a localization: replace it with Chinese screenshots, a Chinese official website, Chinese example questions, and Chinese docs links. Translate terminology according to Chinese conventions.
Change both in the same commit. Content moved from the README into docs/ must also be available in both languages.
Compare item by item: badges, images, links, anchors (Chinese headings generate Chinese anchors, such as #安装), HTML tag closure. The script in Section 8 will report the differences between the two versions. (Real-world case: when the Chinese version was manually edited on the web page, one </p>; there is a leaderboard badge that was only added to the English version.)

7. Project Form Routing

Repository Form	Applicable Scenarios	Reference Files	Key Points
Agent Skill / Plugin / MCP	Skills, plugins, and MCP servers for agents such as Claude Code, Codex, and Cursor	`references/agent-skill.md`	One-line agent installation + `INSTALL.md`, which agents are supported, "why not just let the model do it", copy-pasteable rule snippets
Self-hosted app / Web tool	Privately deployed services, PaaS, self-built platforms	`references/self-hosted.md`	What it benchmarks against, the difference between self-hosting and the cloud, one-click Docker startup, storage choices
Desktop client	Electron, Tauri, native apps	`references/app-desktop.md`	Large UI screenshots, download matrix, usage flow, local-first and privacy statement
CLI / Developer tools	Command-line tools, compilers, package managers	`references/cli-devtools.md`	One-line install, benchmarks with conditions, common commands, output examples
Component library / Framework / SDK	UI component libraries, Node/Python packages	`references/library-framework.md`	One-line proposition, the three steps Init/Add/Use, directly copyable code

The template provides the skeleton. The rules in Sections 1 through 6 take priority over the template.

8. Final Review Checklist

Run the script first (Node 18 or above, no need to install dependencies):

node <本 skill 目录>/scripts/check_readme.mjs README.md README.zh-CN.md

error must all be fixed: dead anchors (including anchors linking to docs/*.md#anchor ), relative files that cannot be found, local paths, leftover placeholders and TODOs, HTML tags that are not closed or are missing > , and a License badge with no LICENSE file.
warning: judge one by one: over 350 lines, exaggerated wording, inconsistent section count, image count, code block count, or badge count between the Chinese and English versions. If inconsistency is truly needed, explain the reason at delivery.
The script automatically looks for README.md in the same directory for comparison. For other filenames, use README.<lang>.md to specify. --pair For other filenames, use --pair to specify.

For things the script cannot check, answer "yes" or "no" for each item:

Four things: the first screen shows what it is, why to use it, how to install it, and what it looks like.
Header: the link row occupies only one line; every badge is useful to readers.
First-screen image: if a before-and-after comparison image can be made, it goes first.
Facts: every claim has a source in the fact list; things only the user knows have already been asked.
Numbers: every number has conditions and a source, and there are no old numbers that contradict other places.
Read-aloud: every sentence can be read in one breath.
Runnable: copying the install command and pasting the snippets really works in a clean environment.
Media: in a repository that will be cloned and installed, no new videos, GIFs, or large files have been added.
Verification: new writing or major revisions have undergone independent verification, and all blockers and highs have been fixed.