Back to Details

oss-readme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

README structure

README 结构

Apply the structure below when creating or improving a README. It follows Evil Martians' approach to promoting open source projects: put the reason to keep reading at the top, and the details below.
This skill owns section order and what each section must contain. It does not own how a sentence reads. Once the sections below are in place, apply oss-writing to the prose inside them.
The README rules belong here: R-DOC-01 opening sentence, R-DOC-02 install and example, R-DOC-03 required links, R-DOC-04 claim accuracy, R-DOC-06 scope statement, R-DOC-07 code block destinations, R-DOC-08 question channel, R-DOC-09 maintenance status, and R-DOC-10 differentiator evidence. R-DOC-05, how each sentence reads, belongs to 
oss-writing
.
When 
oss-audit-report.md
exists at the repository root, read the group addressed to this skill and work from that. Each failing rule there carries the audit's evidence and that rule's 
Check:
text verbatim, so reading 
STANDARD.md
as well adds nothing. Where the file is absent, work from the request as usual.
在创建或改进 README 时应用以下结构。它遵循 Evil Martians 推广开源项目的方法：把让读者继续阅读的理由放在顶部，把细节放在下方。
本 skill 负责章节顺序以及各章节必须包含的内容，但不负责句子的具体写法。各章节的结构确定后，对其中的文字应用 oss-writing。
README 规则归于此处：R-DOC-01 开头句、R-DOC-02 安装与示例、R-DOC-03 必需链接、R-DOC-04 声明准确性、R-DOC-06 适用范围说明、R-DOC-07 代码块用途、R-DOC-08 提问渠道、R-DOC-09 维护状态，以及 R-DOC-10 差异化证据。R-DOC-05，即每句话的具体写法，归 
oss-writing
负责。
当仓库根目录存在 
oss-audit-report.md
时，读取其中分配给本 skill 的部分并据此工作。该文件中每个未通过的规则都附有审计证据，以及该规则逐字保留的 
Check:
文本，因此再读取 
STANDARD.md
不会增加任何信息。如果该文件不存在，则照常根据请求处理。

Three ways in

三种处理方式

The request decides which one runs. Read it before reading the structure below.
To create a README from nothing, write sections 1 to 9 in the order given.
To improve one that exists, read it against the checklist at the end of this skill first. Then fix what fails, in section order, so each fix lands where the reader meets it.
To review one without editing it, report every checklist item that fails. Anchor each finding at the line it fails at, and name what would fix it. Change no file. Write no replacement prose, even where the fix is one word. A request to review, audit, or check a README asks for findings, and a rewrite answers a question nobody asked.
Never invent facts. If the repository does not contain a piece of data you need, such as a benchmark, a file size, a real differentiator from alternatives, or a supported platform list, or you are not sure a number is accurate, ask for it instead of guessing. A README with a fabricated number is worse than one with no number at all.
具体采用哪种方式由请求决定。阅读下方结构前，先阅读请求。
要从零创建 README，请按给定顺序编写第 1 至第 9 节。
要改进现有 README，请先根据本 skill 末尾的检查清单审阅它。然后按章节顺序修复未通过的项目，使每项修复都落在读者首次看到它的位置。
要在不编辑的情况下审查 README，请报告检查清单中所有未通过的项目。每项发现都应定位到未通过项所在的行，并说明应如何修复。不要修改任何文件，也不要编写替代文字，即使修复只需要改动一个词。审查、审计或检查 README 的请求要求提供发现，而不是回答一个没人提出的问题。
绝不要编造事实。如果仓库中缺少所需数据，例如 benchmark、文件大小、相较于替代方案的实际差异化点或受支持的平台列表，或者你不确定某个数字是否准确，应向用户询问，而不是猜测。README 中编造的数字比完全没有数字更糟糕。

Section order

章节顺序

1. Title

1. 标题

A 
#
heading naming the project. Nothing else goes in the heading text.
使用一个以 
#
开头的标题，名称为项目名称。标题文本中不包含其他内容。

2. Opening sentence

2. 开头句

Immediately below the title, one sentence stating what the project is and who it is for. Nothing may come before it: no badge row, no table of contents, no other heading.
Say what the project does in plain terms, without jargon a newcomer would have to look up. If you do not know who the project is for or what makes it different from the alternative a reader already knows, ask rather than guessing at a differentiator. The differentiator does not belong in this sentence. It goes in the 
edge
bullet of the facts list below, which is where R-DOC-10 looks for it and where a number can sit beside it.
Keep it short. The standard-readme spec caps a description at 120 characters, which is a useful ceiling rather than a limit this skill enforces. A two-sentence opener earns its second sentence only when the second sentence carries a fact the first cannot.
The same sentence appears in three places a reader may meet first: the README, the forge repository description, and the 
description
field of any package manifest. Read all three and make them agree. A repository description that contradicts the README is a wrong answer served on every search result page, and nobody who reads it ever sees the correction. The forge description belongs to 
oss-community
, which R-COM-07 names as its owner, so report a mismatch and hand the edit over rather than making it here.
紧接在标题下方，用一句话说明项目是什么以及面向谁。任何内容都不得位于它前面：既不能有徽章行、目录，也不能有其他标题。
用通俗易懂的语言说明项目的用途，不使用新手必须另行查询的术语。如果不知道项目面向谁，或者不知道它相较于读者已经了解的替代方案有何不同，应向用户询问，而不是猜测差异化点。差异化点不属于这句话，而应放在下方事实列表的 
edge
项中；R-DOC-10 会在该位置检查它，数字也可以写在这一项旁边。
开头句应保持简短。standard-readme 规范将描述限制在 120 个字符以内，这是一个有用的上限，但本 skill 并不强制执行。只有当第二句话提供了第一句话无法表达的事实时，两句话的开头才值得保留。
同一句话可能最先出现在三个位置：README、forge 仓库描述，以及任何 package manifest 的 
description
字段。读取全部三处，并确保它们表达一致。与 README 相矛盾的仓库描述会在每个搜索结果页上提供错误信息，而读者永远看不到后续修正。forge 描述归 
oss-community
负责，R-COM-07 明确指定了这一归属，因此应报告不一致并移交修改，而不是在此处处理。

3. Badges

3. 徽章

Optional, and capped at three. Read references/badges.md before writing or editing a badge row: it carries the cap, the order, the placement, the live-fact test that decides what never gets a badge, and the fallback badge for a repository no registry serves.
The version badge itself is per ecosystem. 
references/ecosystems/<name>.md
carries the endpoint, how its label behaves, and what to link it to, one file per ecosystem, and 
references/badges.md
links all eleven. That file also carries the ecosystem's install command, which section 5 needs.
Do not move the row above the 
#
heading, and do not raise the cap. R-DOC-01 exists so a reader's first five seconds buy them the sentence, and a row above the title spends them on shields.
When improving an existing README, delete every badge beyond those three. If a deleted badge carried a real fact, such as a bundle size or a dependency count, state that fact as a bullet in the facts list instead, where it reads stronger than a badge.
徽章是可选的，最多只能有三个。编写或编辑徽章行前，先阅读 references/badges.md：其中包含数量上限、顺序、位置、决定哪些内容不应使用徽章的动态事实测试，以及没有 registry 为仓库提供服务时使用的备用徽章。
版本徽章本身因 ecosystem 而异。
references/ecosystems/<name>.md
包含对应 endpoint、label 的行为方式及其链接目标，每个 ecosystem 一个文件；
references/badges.md
链接到全部十一个文件。该文件还包含此 ecosystem 的安装命令，第 5 节需要使用。
不要把徽章行移到 
#
标题上方，也不要提高数量上限。R-DOC-01 的目的是让读者最初五秒先获得关键信息，而置于标题上方的徽章行会把这五秒花在盾牌图标上。
改进现有 README 时，删除所有超出三个限制的徽章。如果被删除的徽章承载了真实事实，例如 bundle size 或依赖项数量，应将该事实改为事实列表中的一项；在那里，它比徽章更有说服力。

Table of contents, only where the renderer generates no outline

目录，仅在渲染器无法生成大纲时使用

This is the one place a table of contents can go, which is why it sits here rather than in the numbered order. Add one only when the target renderer generates no outline and the README runs longer than about two screens. GitHub already generates an outline from headings, so do not duplicate it there unless the project publishes the README somewhere else that needs one.
这是目录唯一可以出现的位置，因此它位于此处，而不纳入编号顺序。仅当目标渲染器无法生成大纲，并且 README 长度超过约两个屏幕时，才添加目录。GitHub 已经可以根据标题生成大纲，因此不要在那里重复添加，除非项目还会把 README 发布到需要目录的其他位置。

4. Facts

4. 事实

Three to five bullets directly under the opening sentence, or under the badge row when there is one. No heading introduces them. A 
## Features
heading turns a pitch into a spec sheet and pushes the list below the fold, which is the one place it cannot do its job.
This list is where R-DOC-10 is satisfied: at least one bullet has to name a boundary, a measured number, or a competing project, and that name has to be checkable against the repository. A list of five adjectives passes no rule here.
Every bullet answers a question the reader is actually asking. The five questions are:
  • scope, meaning what the project covers and where it runs: forges, platforms, registries, runtimes, frameworks, languages
  • scale, meaning how much the reader gets: counts of the things the project ships
  • fit, meaning what the project asks of the reader: runtimes, prerequisites, dependency count, setup cost
  • edge, meaning what it beats, named, with a number
  • proof, meaning a measured benchmark, an exact size, or a short code comparison against the closest alternative
The scope bullet is not optional whenever the project has a boundary. It is the bullet that lets a reader self-select in or out, and it is the one most often missing, because a boundary lives in configuration and reference files rather than in the code an author is proud of.
A screenshot or diagram may replace a bullet where it replaces a paragraph of text, with alt text that carries the same information.
在开头句正下方放置三到五个项目符号；如果有徽章行，则放在徽章行正下方。不要使用标题引入这个列表。
## Features
标题会把项目介绍变成规格表，并把列表推到首屏之外，而那里正是列表无法发挥作用的位置。
R-DOC-10 在这里得到满足：至少一个项目符号必须指出边界、可测量的数字或竞争项目，而且该内容必须能够根据仓库进行核实。五个形容词的列表无法满足这里的任何规则。
每个项目符号都应回答读者真正关心的问题。这五个问题分别是：
  • scope，即项目涵盖什么以及在哪里运行：forges、platforms、registries、runtimes、frameworks、languages
  • scale，即读者能够获得多少内容：项目交付内容的数量
  • fit，即项目要求读者付出什么：runtimes、前置条件、依赖项数量、设置成本
  • edge，即项目相较于什么方案更胜一筹，必须指名竞争项目并附上数字
  • proof，即实测 benchmark、精确大小，或与最接近的替代方案进行的简短代码对比
只要项目存在边界，scope 项就不可省略。它能帮助读者判断自己是否适合使用该项目，也是最常被遗漏的一项，因为边界通常存在于配置和参考文件中，而不是作者引以为豪的代码里。
如果截图或图表能够替代一段文字，也可以用它替代一个项目符号；alt text 必须传达相同的信息。

The rejection test

拒绝测试

A candidate that answers none of the five questions is cut, however easy it was to extract from the source tree and however true it is. Ease of extraction is the trap: an author reading their own repository finds the facts the repository states about itself, not the facts a stranger needs.
Worked example, from this kit's own repository. "Every skill body stays under 500 lines" is true, checkable, and sitting in plain sight. It answers no reader question: nobody installs a project to obtain short files. The same evidence answers 
fit
once it is turned around, as in "runs on Node 22 or Bun with nothing installed". The fact was never wrong, only pointed at the maintainer instead of the reader.
如果某个候选项没有回答上述五个问题中的任何一个，就应将其删除，无论它从源代码树中提取起来多么容易、其内容多么真实。提取难度正是一个陷阱：作者阅读自己的仓库时，找到的是仓库对自身的描述，而不是陌生读者需要的信息。
下面是一个来自本 kit 自身仓库的示例。“每个 skill 正文都不超过 500 行”这一说法真实、可核实，而且一目了然，但它没有回答任何读者问题：没人会为了获得简短文件而安装一个项目。同一份证据经过转换后就可以回答 
fit
，例如“可在 Node 22 或 Bun 上运行，无需安装任何依赖”。事实本身从未出错，只是它指向了维护者，而不是读者。

Gather, then let the maintainer pick

收集候选事实，再交由维护者选择

Never choose the final bullets alone. Sweep the repository for every candidate, then present the slate and stop.
  1. Read the manifests, the lockfile, the CI configuration, the reference and configuration files, the release configuration, and the source. Collect every candidate fact and record the file each one came from.
  2. Sort candidates into the five slots. Anything that fits no slot goes on the rejected list with the reason.
  3. Present the slate: candidates grouped by slot, each with its source file, and the rejected list below with reasons. Show more candidates than will be used.
  4. Ask the maintainer to pick three to five, and to supply anything the repository cannot prove, such as a benchmark, a real differentiator, or a support claim.
  5. Write only what they picked.
A slate reads like this. This one is the slate this kit's own README came from:
text
Candidate facts  (pick 3 to 5)

  scope  1. GitHub and GitLab, 57 of 61 rules on both
            src: STANDARD.md, Forges: lines
  scope  2. Publishing for npm, RubyGems, PyPI, crates.io
            src: skills/oss-publish/references/
  scale  3. 61 rules, each with the check it is scored by
            src: STANDARD.md, 59 "### R-" headings
  fit    4. Node 22 or Bun, nothing installed
            src: skills/oss-skill/scripts/validate.mjs
  edge   5. Scores a repository, where a checklist only lists it
            src: skills/oss-audit/SKILL.md

Rejected, answers no reader question:
  - every skill body under 500 lines
  - imports only Node built-in modules  (keep as evidence for fit 4)
Stopping here costs one round trip and is the only reliable filter. A writer left alone picks what the source tree makes easy, which is how a facts list ends up describing how a project is built rather than what it does.
绝不要独自决定最终的项目符号。先扫描仓库中的所有候选项，然后展示候选清单并停下。
  1. 读取 manifests、lockfile、CI 配置、参考与配置文件、发布配置以及源代码。收集每个候选事实，并记录其来源文件。
  2. 将候选项归入五个槽位。任何不适合任何槽位的内容都放入拒绝列表，并注明原因。
  3. 展示候选清单：按槽位分组，为每项标注来源文件，并在下方列出拒绝项及原因。展示的候选项数量应多于最终采用的数量。
  4. 请维护者选择三到五项，并补充仓库无法证明的内容，例如 benchmark、实际差异化点或支持声明。
  5. 只编写维护者选中的内容。
候选清单示例如下。这正是本 kit 自身 README 使用的候选清单：
text
Candidate facts  (pick 3 to 5)

  scope  1. GitHub and GitLab, 57 of 61 rules on both
            src: STANDARD.md, Forges: lines
  scope  2. Publishing for npm, RubyGems, PyPI, crates.io
            src: skills/oss-publish/references/
  scale  3. 61 rules, each with the check it is scored by
            src: STANDARD.md, 59 "### R-" headings
  fit    4. Node 22 or Bun, nothing installed
            src: skills/oss-skill/scripts/validate.mjs
  edge   5. Scores a repository, where a checklist only lists it
            src: skills/oss-audit/SKILL.md

Rejected, answers no reader question:
  - every skill body under 500 lines
  - imports only Node built-in modules  (keep as evidence for fit 4)
在这里停下会多进行一次往返，但这是唯一可靠的筛选方式。如果让作者独自选择，他们往往会挑选源代码树中最容易提取的信息，最终导致事实列表描述项目的构建方式，而不是项目能够为用户提供什么。

Bullet shape

项目符号的形态

Lead with the claim in bold, close it with a period, then give the evidence:
markdown
- **Both forges.** Scores GitHub and GitLab repositories.
- **No install.** The validator runs on Node 22 or Bun with nothing added.
The bold must be the claim, not a label. 
- **Performance:** it is faster
is banned by oss-writing, and the carve-out that permits the form above is written there. Test it by deleting everything after the bold: "Performance." says nothing, so it was a label; "Both forges." says something, so it was a claim.
Bold is optional. A plain sentence bullet is fine, and a project whose facts do not compress into one-word claims should not force them.
先用粗体突出主张，以句号收尾，然后再提供证据：
markdown
- **Both forges.** Scores GitHub and GitLab repositories.
- **No install.** The validator runs on Node 22 or Bun with nothing added.
粗体部分必须是主张，而不是标签。oss-writing 禁止使用 
- **Performance:** it is faster
这种形式，而允许上方示例形式的例外规则写在 oss-writing 中。判断方法是删除粗体后的所有内容：“Performance.”没有传达任何信息，因此它只是标签；“Both forges.”传达了明确主张，因此它才是合格的主张。
粗体是可选的。普通的句子型项目符号也可以；如果项目的事实无法压缩成简短主张，就不应强行使用粗体。

5. Install and example

5. 安装与示例

Two fenced code blocks back to back: an install command, then a minimal usage example, in that order. The second block must show the project being used, not a second way to install it; two install blocks with no usage block fails this section even when the two commands differ. Both must appear before any section about design, motivation, or comparisons.
Keep the usage example small, 4 to 10 lines, and show its result when a short language comment can do so without making the example invalid or misleading. Otherwise show the output in a separate fenced block. The title, the opening sentence, the facts, and this pair fit on one screen together. Here is that shape, carrying the slate above through to what it produced. This is 
README.md
from the repository this skill ships in, abridged to two facts and with its badge row cut:
markdown
undefined
使用两个紧挨着的 fenced code blocks：先放安装命令，再放最小用法示例。第二個代码块必须展示项目的使用方式，而不是另一种安装方式；即使两个命令不同，如果只有两个安装代码块而没有用法代码块，本节仍不合格。两个代码块都必须位于任何设计、动机或比较内容之前。
用法示例应保持精简，控制在 4 到 10 行。如果能用简短的 language comment 展示结果且不会使示例无效或产生误导，就在示例中展示结果；否则使用单独的 fenced block 展示输出。标题、开头句、事实列表和这一对代码块应能共同放在一个屏幕内。下面展示了这种形态，它将上方的候选清单转化为最终内容。这是从本 skill 所在仓库生成的 README.md，示例中缩减为两个事实，并删除了徽章行：
markdown
undefined

oss-kit

oss-kit

Curated agent skills for open source maintainers.
  • 61 rules. Each states the check it is scored by and the one skill that fixes it.
  • Both forges. 57 of the 61 rules score GitHub and GitLab alike.
bash
npx skills add svyatov/oss-kit
Then ask your agent:
text
Audit this repository against the oss-kit standard.
text
Audited 52 applicable rules: 49 pass, 2 fail, 1 unknown, 9 not applicable.

Do not copy the shape from a README you have heard of. Well-known projects put a logo, a row of translation links, or a pull quote between the title and the opening sentence, and many place the install command well below the first example, so each teaches a departure from R-DOC-01 or R-DOC-02 along with the shape.

The install command belongs to the ecosystem the project publishes to, and `references/ecosystems/<name>.md` carries it, along with which form to show when the ecosystem has more than one.

If the project has no install step, for example a script meant to be copied, say so instead of showing an empty or invented command.
Curated agent skills for open source maintainers.
  • 61 rules. Each states the check it is scored by and the one skill that fixes it.
  • Both forges. 57 of the 61 rules score GitHub and GitLab alike.
bash
npx skills add svyatov/oss-kit
Then ask your agent:
text
Audit this repository against the oss-kit standard.
text
Audited 52 applicable rules: 49 pass, 2 fail, 1 unknown, 9 not applicable.

不要照搬你听说过的某个 README 的形态。知名项目可能会在标题与开头句之间放置 logo、翻译链接行或引用文字，还有许多项目会把安装命令放在第一个示例之后，因此这些项目中的每一项都会教授一种偏离 R-DOC-01 或 R-DOC-02 的做法。

安装命令应属于项目发布到的 ecosystem；`references/ecosystems/<name>.md` 中记录了该命令，也说明了 ecosystem 提供多种安装方式时应展示哪一种。

如果项目没有安装步骤，例如它只是一个供人复制使用的 script，应直接说明，而不要展示空命令或编造命令。

6. Where to start, when there is more than one way in

6. 有多个入口时，从何处开始

A project that ships one command needs nothing here. A project that ships several commands, packages, subcommands, or skills has to answer which one a reader runs first, and R-DOC-02's install-then-example pair cannot answer it: the reader now has the thing installed and several doors.
Name exactly one thing to run first, in a sentence, and say what it gives back. When the parts have a natural sequence, give the sequence as a short list. When they do not, say so and stop; a fabricated order is worse than none.
Cover the empty-repository case separately when it differs, because a reader starting from nothing cannot use an entry point that inspects existing work.
markdown
undefined
只提供一个命令的项目不需要这一节。提供多个命令、packages、subcommands 或 skills 的项目必须回答读者应该首先运行哪一个，而 R-DOC-02 的“安装后示例”这一组合无法回答该问题：读者此时已经完成安装，却面对多个入口。
用一句话明确指定首先运行的一个对象，并说明运行后会得到什么。当各部分存在自然顺序时，用简短列表给出该顺序。如果没有自然顺序，就直接说明并停止；编造顺序比不提供顺序更糟糕。
当从空仓库开始的情况有所不同，应单独说明，因为从零开始的读者无法使用需要检查现有成果的入口。
markdown
undefined

Where to start

Where to start

Run 
oss-audit
first. It scores the repository and names which of the other skills to run, in what order.
Starting from an empty repository, there is nothing to score yet:
  1. oss-community
    for the license, code of conduct, and contributing guide
  2. oss-readme
    for the README
  3. oss-ci
    for tests on push and on every change request

This section rests on no external convention, because the published README guidance does not address projects with several entry points at all.
Run 
oss-audit
first. It scores the repository and names which of the other skills to run, in what order.
Starting from an empty repository, there is nothing to score yet:
  1. oss-community
    for the license, code of conduct, and contributing guide
  2. oss-readme
    for the README
  3. oss-ci
    for tests on push and on every change request

这一节不依赖任何外部惯例，因为已发布的 README 指导完全没有涵盖具有多个入口的项目。

7. Getting started

7. 快速入门

A step-by-step guide for adding the tool to an existing project, with explicit commands the reader can copy without thinking. Cover every step, including documented runtime and tool prerequisites.
Then run the guide instead of reading it. Make an empty directory outside the repository with 
mktemp -d
and change into it. Install the lowest runtime version the project claims to support, plus the prerequisites the guide names and nothing else. Paste each command in the order the guide gives, and read what it prints. Do not change global configuration or install a package globally to make a step pass, because the reader will not. Fix every gap you hit, then say in the summary which runtime version the run used.
提供一份分步骤指南，说明如何将工具添加到现有项目中。命令应明确具体，读者无需思考即可复制。指南必须涵盖每个步骤，包括文档中列出的 runtime 和工具前置条件。
完成指南后，不要只阅读它，而要实际运行。使用 
mktemp -d
在仓库外创建一个空目录并进入该目录。安装项目声称支持的最低 runtime 版本，以及指南列出的前置条件，不安装任何其他内容。按指南给出的顺序粘贴并执行每条命令，并阅读其输出。不要为了让某一步通过而修改全局配置或全局安装 package，因为真实读者不会这样做。修复过程中遇到的每个问题，并在总结中说明本次运行使用的 runtime 版本。

8. Help and status

8. 帮助与状态

Two short items, usually near the links. Both satisfy rules, and both are cheap enough that omitting them is never a considered choice, only an oversight.
Say where to ask a question and where to report a defect, per R-DOC-08. The channel has to be public, searchable, and reachable by URL without proprietary client software, so that the next reader with the same question finds the answer already written. One link covers both when the project routes questions and defects to the same place, which for most projects means the issue tracker. A private mailbox does not count, and neither does an invite-only chat.
Say whether the project is maintained, per R-DOC-09. One sentence about the support the maintainer intends to give. A project that has stopped says so in the first heading of the README, or in the repository description, or with a no-maintenance-intended badge, or by being archived; any of those satisfies the rule without a sentence.
提供两个简短项目，通常放在链接附近。两者都用于满足规则，而且成本极低；省略它们从来不是经过权衡的选择，而只是疏忽。
根据 R-DOC-08，说明提问和报告缺陷的渠道。该渠道必须公开、可搜索，并且无需专有客户端软件即可通过 URL 访问，这样遇到相同问题的下一位读者就能看到已经写好的答案。当项目把问题和缺陷都导向同一个位置时，一个链接即可同时满足两项要求，对大多数项目而言，这个位置就是 issue tracker。私人邮箱不算，仅限受邀加入的 chat 也不算。
根据 R-DOC-09，说明项目是否仍在维护。用一句话说明维护者打算提供哪些支持。已经停止维护的项目应在 README 的第一个标题、仓库描述中通过“不再维护”徽章，或通过归档状态来表明；任何一种方式都足以满足规则，无需额外添加句子。

9. Links

9. 链接

Link the license file, 
CHANGELOG.md
, and 
CONTRIBUTING.md
. Confirm each target exists in the repository before adding the link.
链接到 license 文件、
CHANGELOG.md
和 
CONTRIBUTING.md
。添加链接前，确认每个目标都存在于仓库中。

Formatting for skimmers

便于快速浏览的排版

  • Headings for hierarchy, horizontal rules between layers.
  • Lists over dense paragraphs.
  • On GitHub or GitLab, put a must-not-miss line in an alert: 
    > [!NOTE]
    , 
    > [!TIP]
    , 
    > [!IMPORTANT]
    , 
    > [!WARNING]
    , or 
    > [!CAUTION]
    , each on its own line with the content in the blockquote below it.
    markdown
    > [!WARNING]
> Version 3 drops Node 18. Pin to `^2` if you need it.
    GitHub and GitLab render these as callouts. For any other target renderer, verify the preview or use an ordinary blockquote because unsupported renderers may expose the 
    [!TYPE]
    marker. Use alerts only for crucial information and limit them to one or two per README.
  • Every section should reach a reason to keep reading quickly; a reader abandons at the first boring stretch.
  • 使用标题表达层级，使用水平分隔线区分不同层级。
  • 使用列表，而不是信息密集的段落。
  • 在 GitHub 或 GitLab 上，使用 alert 呈现不可错过的信息：
    > [!NOTE]
    、
    > [!TIP]
    、
    > [!IMPORTANT]
    、
    > [!WARNING]
    或 
    > [!CAUTION]
    ，每种类型单独占一行，内容放在下方的 blockquote 中。
    markdown
    > [!WARNING]
> Version 3 drops Node 18. Pin to `^2` if you need it.
    GitHub 和 GitLab 会把这些内容渲染为 callout。对于其他目标渲染器，应检查预览效果，或使用普通 blockquote，因为不支持的渲染器可能会直接显示 
    [!TYPE]
    标记。alert 只用于最关键的信息，每个 README 限用一到两个。
  • 每一节都应尽快为读者提供一个继续阅读的理由；读者往往会在第一段乏味的内容处离开。

Every code block says what consumes it

每个代码块都应说明使用位置

R-DOC-07. A fenced block is a box of text, and a box of text carries no clue about where it goes. Two blocks in a row, one a shell command and one the body of a configuration file, render identically and get pasted into the same place.
Give every block a language tag. Where no tag fits, such as a prompt typed to an agent or a block of program output, use 
text
rather than leaving the fence bare, so the absence of a tag never has to be interpreted.
Then, for every block whose destination is not "paste this in a terminal", put one short sentence above it naming the destination: a file path, a tool, a prompt, a configuration key.
markdown
Install it:

```bash
npx skills add svyatov/oss-kit
```

Add to `.eslintrc.json`:

```json
{ "extends": ["oss-kit"] }
```
A first-line comment inside the block naming the destination is a reasonable addition, and not a replacement: JSON and plain-text prompts have no comment syntax, which is exactly where the ambiguity is worst.
R-DOC-07。fenced block 只是一个文本框，本身无法说明内容要放到哪里。两个相邻的代码块，一个是 shell command，另一个是配置文件正文，渲染效果完全相同，却会被粘贴到同一个位置。
为每个代码块添加 language tag。如果某段内容没有合适的标签，例如输入给 agent 的 prompt 或程序输出，应使用 
text
，不要留空围栏，从而避免读者猜测是否缺少标签。
然后，对于每个并非用于“粘贴到终端”的代码块，在其上方添加一句简短说明，指出内容的使用位置，例如文件路径、工具、prompt 或配置项。
markdown
Install it:

```bash
npx skills add svyatov/oss-kit
```

Add to `.eslintrc.json`:

```json
{ "extends": ["oss-kit"] }
```
在代码块内使用首行 comment 标明使用位置，也是合理做法，但不能替代代码块上方的说明：JSON 和纯文本 prompt 没有 comment 语法，而这恰恰是最容易产生歧义的情况。

Accuracy

准确性

Before finishing, read every package manifest, the lockfile, the CI configuration, the release configuration, and the source. Match every version number, install command, import path, CLI flag, prerequisite, and support claim quoted in the README against those files. For an installation command, also confirm that the upstream project or registry owner documents that exact package and command. A manifest proves what this checkout declares, not that an external package name is legitimate.
完成前，读取所有 package manifest、lockfile、CI 配置、发布配置和源代码。将 README 中引用的每个版本号、安装命令、import path、CLI flag、前置条件和支持声明，与这些文件逐一核对。对于安装命令，还应确认上游项目或 registry owner 明确记录了对应的 package 和命令。manifest 只能证明当前 checkout 声明了什么，不能证明外部 package 名称确实存在。

Checklist before finishing

完成前的检查清单

  1. The opening sentence alone states what the project is and who it is for, and nothing precedes it.
  2. The opening sentence, the forge repository description, and any manifest 
    description
    field say the same thing.
  3. Every number and claim is real: sourced from the repository, from the person who asked for the README, or from an actual measurement.
  4. The facts list ran through the slate: candidates gathered with their sources, rejects named, and the maintainer picked the three to five that shipped.
  5. A scope bullet names the forges, platforms, registries, or runtimes supported, unless the project genuinely has no boundary.
  6. No shipped bullet describes how the project is built rather than what a reader gets.
  7. At least one bullet above the first 
    ##
    heading names a boundary, a measured number, or a competing project, and the repository backs it.
  8. The install and usage blocks appear in that order, before any design, motivation, or comparison content.
  9. The usage example is self-explanatory and shows its result without invalid or misleading syntax.
  10. Every fenced block carries a language tag, and every block not destined for a shell has a sentence above it naming where it goes.
  11. A project with more than one entry point names exactly one to run first, and covers the empty-repository case when it differs.
  12. Every getting-started command was pasted, in order, into a fresh 
    mktemp -d
    directory on the lowest supported runtime, and each one succeeded.
  13. A public, searchable channel is linked for questions and for defect reports.
  14. The maintenance status is stated, or an equivalent repository signal carries it.
  15. The license, changelog, and contributing links resolve to files that exist.
  16. Every version, command, and support claim matches the manifest, the CI configuration, and the source.
  17. Skimming only headings and the facts list still tells the story.
  18. The draft has been through oss-writing: 
    node <oss-writing skill directory>/scripts/prose.mjs README.md
    (a sibling of this skill's directory) reports no findings. A hand-rolled grep for dashes or banned words does not count. Where oss-writing is not installed, say so rather than reporting this item as passing.
  19. Every image has meaningful alt text, and repository images use relative paths.
Fix what the checklist catches, then read each R-DOC rule's 
Check:
line in 
STANDARD.md
(in the 
oss-audit
skill's directory, a sibling of this one) against the README as it now stands. Start the checklist again after each fix, since reordering a section moves what the next item is looking at. Do not report done while any item or any cited rule still fails.
  1. 仅通过开头一句话就能说明项目是什么以及面向谁，并且它前面没有任何内容。
  2. 开头句、forge 仓库描述和任何 manifest 的 
    description
    字段表达一致。
  3. 每个数字和声明都真实：来源于仓库、提出 README 请求的人或实际测量结果。
  4. 事实列表经过候选清单流程：收集候选项并记录来源，列出拒绝项及原因，再由维护者选择最终采用的三到五项。
  5. scope 项指出受支持的 forges、platforms、registries 或 runtimes，除非项目确实没有任何边界。
  6. 最终采用的任何项目符号都没有描述项目的构建方式，而是说明读者能够获得什么。
  7. 第一个 
    ##
    标题之前至少有一个项目符号指出了边界、可测量的数字或竞争项目，并且仓库能够支持该内容。
  8. 安装和用法代码块按此顺序出现，并位于任何设计、动机或比较内容之前。
  9. 用法示例含义清晰，能够在不包含无效或误导性语法的情况下展示结果。
  10. 每个 fenced block 都带有 language tag，每个并非供 shell 使用的代码块上方都有一句说明其使用位置的文字。
  11. 具有多个入口的项目明确指定了首先运行的一个对象，并在情况不同时涵盖从空仓库开始的场景。
  12. 每条快速入门命令都按顺序粘贴到由 
    mktemp -d
    创建的新目录中，并在最低支持的 runtime 上成功执行。
  13. 为提问和缺陷报告提供了公开、可搜索的渠道。
  14. 已说明维护状态，或由等效的仓库信号承载该状态。
  15. license、changelog 和 contributing 链接都指向实际存在的文件。
  16. 每个版本、命令和支持声明都与 manifest、CI 配置及源代码一致。
  17. 即使只浏览标题和事实列表，也能理解整个项目。
  18. 草稿已经经过 oss-writing 检查：
    node <oss-writing skill directory>/scripts/prose.mjs README.md
    （该目录与本 skill 的目录同级）未报告任何问题。自行编写 grep 来查找短横线或禁用词不算通过检查。如果未安装 oss-writing，应直接说明，而不能将此项报告为已通过。
  19. 每张图片都有含义明确的 alt text，仓库中的图片使用相对路径。
修复检查清单发现的问题后，对照当前的 README，逐条读取 
STANDARD.md
中每条 R-DOC 规则的 
Check:
行（该文件位于 
oss-audit
skill 的目录中，与本 skill 的目录同级）。每次修复后重新开始检查清单，因为重新排列章节会改变下一项检查所对应的位置。只要仍有任何检查项或引用的规则未通过，就不能报告工作已经完成。