oss-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Repo prose

仓库文案

Write with clarity and force for a reader whose first language is not English. Be terse.

This skill owns how the sentence reads, which is one rule: R-DOC-05 documentation prose. The skill that owns the artifact owns what goes in it, and where a caller states an exception, the caller wins.

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.

为第一语言不是英语的读者清晰、有力地写作。务必简洁。

本 skill 负责句子的表达方式，具体遵循一条规则：R-DOC-05 文档写作。负责目标 artifact 的 skill 决定其中应包含什么；如果调用方（caller）明确规定例外，则以调用方为准。

当仓库根目录存在

oss-audit-report.md

时，读取其中针对本 skill 的分组，并据此工作。该文件中每条失败规则都附有 audit 证据和该规则逐字引用的

Check:

文本，因此再读

STANDARD.md

不会增加任何信息。如果文件不存在，则照常根据请求处理。

Read the local contract first

先阅读本地约定

Before drafting, read the repository's instructions, contribution guide, templates, and the most recent accepted examples of the same artifact. They decide the commit convention, the required sections, the terminology, and the audience. Follow the convention the repository declares rather than inventing one, and keep required template sections and legally mandated wording. Past examples show a convention's shape. They do not lift a limit this skill sets: only a stated rule does.

Verify every claim against the diff, the source, or command output. Prose that reads well and says something untrue is the one failure no rule below catches.

起草前，先阅读仓库说明、贡献指南、模板，以及同类 artifact 最近被采纳的示例。它们决定 commit 约定、必需章节、术语和受众。遵循仓库声明的约定，不要自行发明；同时保留模板要求的章节和法律强制要求的措辞。过往示例展示约定的形式，但不能解除本 skill 设置的限制。只有明确写出的规则可以豁免这些限制。

根据 diff、源代码或命令输出核实每一项陈述。文字即使通顺却陈述了不实内容，是以下任何规则都无法发现的唯一失败。

Core rules (all artifacts)

核心规则（适用于所有 artifact）

State things in positive form. Keep a negative where prohibition is the point.

Use specific, concrete, definite words:

fails on files over 2 MB

, not

fails on large inputs

Omit needless words. Never drop a word that carries a fact, condition, or scope.
Avoid succession of loose sentences.
Keep related words together.
Keep to one tense in summaries.
Write one instruction per sentence.
Keep an instruction to 20 words. Keep any other sentence to 25.
Write one topic per paragraph. Use at most six sentences per paragraph.
Do not stack more than three nouns in a row.
Use parallel form for parallel ideas.
Put the most important word at the end of the sentence.
Use serial commas.
Put conditions before instructions: "to reset the cache, run
```
make clean
```
".
Use vertical lists for complex or sequential content.

尽量使用肯定表达。只有当禁止行为本身是重点时，才保留否定表达。
使用具体、明确、确定的词语：写
```
fails on files over 2 MB
```
，不要写
```
fails on large inputs
```
。
删去无用的词。绝不能删除承载事实、条件或范围的词。
避免连续堆叠松散句子。
将相关词语放在一起。
摘要中只使用一种时态。
每个句子只写一项指示。
将指示句控制在 20 个词以内，其他句子控制在 25 个词以内。
每段只写一个主题，每段最多六句。
不要连续堆叠超过三个名词。
并列含义使用平行结构。
把最重要的词放在句末。
使用 serial commas（系列逗号）。
先写条件，再写指示："要重置缓存，请运行
```
make clean
```
"。
复杂或按顺序展开的内容使用纵向列表。

One instruction per sentence

每个句子只写一项指示

Bad: Install the package and then set the token before you run the build.
Good: Install the package. Set the token. Run the build.

错误：安装软件包，然后在构建前设置 token。
正确：安装软件包。设置 token。执行构建。

Noun cluster

名词堆叠

Bad: network access cost optimization proposal
Good: a proposal to optimize the cost of network access

错误：网络访问成本优化提案
正确：一份优化网络访问成本的提案

Triggers (read the reference before writing)

触发条件（写作前阅读参考资料）

Before naming a branch, or writing a commit message or change request description, read references/commits-and-change-requests.md.
Before writing or replying to a review comment, read references/code-review.md.
Before writing a README or documentation, read references/docs-and-readme.md.
Before writing agent-facing text (AGENTS.md, skills, prompts), hold every sentence to 20 words and keep one meaning per word.

Ship the revision, not the draft.

在命名 branch 或编写 commit message、change request 描述前，阅读 references/commits-and-change-requests.md。
在编写或回复 review comment 前，阅读 references/code-review.md。
在编写 README 或文档前，阅读 references/docs-and-readme.md。
在编写 agent-facing text（AGENTS.md、skills、prompts）前，每句控制在 20 个词以内，并确保每个词只表达一个含义。

交付修订稿，不要交付草稿。

Check before returning

返回前检查

Read the draft against this list and fix what it catches.

Find the longest sentence and count its words. Over 25, or over 20 for an instruction, and it splits. Two clauses joined by
```
and
```
or
```
so
```
are usually two sentences; a relative clause opening with
```
which
```
is usually the second half of one.
Count the characters in a commit subject or change request title, plus any
```
 (#123)
```
the forge appends on squash. Over 72, and it moves detail into the body. A subject that lists several changes means the commit should be split.
No em dashes, en dashes, or
```
--
```
. In short technical prose they are a reliable machine-written tell. A period, comma, colon, or pair of parentheses carries the same break.
No emoji anywhere, including headings and bullets. Their width and glyph vary by terminal and font, so they break alignment in fixed-width contexts.
Headings in sentence case, not Title Case. The Google style guide prescribes it. Mixing the two inside one document reads as text assembled from two sources.
Straight ASCII quotes. Curly quotes break a copy-paste into a shell or a config file, and the reader cannot tell by eye which they got.
Never inflect a code element or use one as a verb:
```
send a POST request
```
, not
```
POST the data
```
;
```
the --force flag
```
, not
```
force it
```
.
No promotional adjective describing the project:
```
robust
```
,
```
powerful
```
,
```
seamless
```
,
```
comprehensive
```
,
```
blazing
```
,
```
effortless
```
. Name the property instead:
```
retries 3 times
```
,
```
no config file
```
.
No recap section restating what the text just said. The reader just read it.
No boilerplate caveats. State a precondition, limitation, or risk when it changes what the reader should do. A caveat that changes nothing trains the reader to skip the one that matters.
No contrast with an invented alternative. In
```
X rather than Y
```
or
```
X instead of Y
```
, keep Y only when Y exists outside the draft. A prior behavior, a real endpoint, or a default the reader would hit qualifies.
```
Instead of returning a deck nobody asked for
```
names code nobody wrote. Delete that clause and let X stand.
No clause telling the reader how to weigh a fact just stated. Delete the clause and see what is lost. If no fact goes with it, it was defending the sentence. A constraint or a consequence is a fact and stays. An alternative stays only when the contrast check above keeps it.

Fix what the list catches, then read the revision against the list again, because a rewritten sentence can break a rule the original passed. Return the draft only when a full pass catches nothing.

If the draft still reads padded, generic, or promotional after that pass, the remaining fault is lexical. Check it against references/tells.md, which names each pattern and what to write instead.

Run

scripts/prose.mjs

in this skill's own directory over the files you touched, before returning them. It reports the part of the list above that a regex can decide, with a file and a line for each hit. It needs Node 22 or later, or Bun, and nothing installed:

node <this skill's directory>/scripts/prose.mjs README.md docs/

By default it reports what R-DOC-05 names: em and en dashes,

--

, emoji, Title Case headings, and the six promotional words that rule lists.

--house

adds the rest of the house style, where every hit needs your judgement rather than a fix.

--length

adds sentences over 25 words and is noisy on purpose. It exits 1 when it reports anything.

The script skips fenced blocks and inline code, so a quoted dash in sample output is not a finding, and a rule may name inside backticks the pattern it forbids. It cannot tell a heading's proper noun from an ordinary capitalized word, so a wrongly flagged heading means passing

--proper

with a file of terms rather than rewriting the heading. A heading that a required template sets stays as the template writes it: its hit is expected, so leave it.

An install that brings in this skill alone still has the script, because it sits inside this directory. Anything calling it from another skill checks that it is there and reads the files itself when it is not.

To enforce the same rules in CI rather than at the end of a draft, see references/linting.md. It maps each checkable rule onto a checker, and names the rules no checker can decide.

对照清单审阅草稿，并修复发现的问题。

找出最长句并统计词数。如果超过 25 个词，或指示句超过 20 个词，就拆分句子。由
```
and
```
或
```
so
```
连接的两个分句通常是两个句子；以
```
which
```
开头的 relative clause（关系从句）通常是一个句子的后半部分。
统计 commit subject 或 change request title 的字符数，包括 forge 在 squash 时追加的
```
 (#123)
```
。超过 72 个字符时，把细节移入正文。列出多项变更的 subject 表明应拆分 commit。
不得使用 em dash、en dash 或
```
--
```
。在简短技术文本中，它们是机器写作的明显特征。句号、逗号、冒号或成对括号可以承担同样的断句作用。
任何位置都不得使用 emoji，包括标题和列表项。它们的宽度和字形会随终端和字体变化，因此会破坏等宽环境中的对齐。
标题采用 sentence case，不采用 Title Case。Google 风格指南规定采用 sentence case。在同一文档中混用两种形式，会让读者认为文本是从多个来源拼接而成的。
使用直立的 ASCII 引号。弯引号会破坏复制粘贴到 shell 或配置文件中的内容，读者也无法凭肉眼判断实际使用了哪一种。
绝不对代码元素做屈折变化，也不得把代码元素用作动词：应写
```
send a POST request
```
，而不是
```
POST the data
```
；应写
```
the --force flag
```
，而不是
```
force it
```
。
不要用宣传性形容词描述项目：
```
robust
```
、
```
powerful
```
、
```
seamless
```
、
```
comprehensive
```
、
```
blazing
```
、
```
effortless
```
。直接说明属性，例如：
```
retries 3 times
```
、
```
no config file
```
。
不要添加复述刚才内容的 recap 章节。读者刚刚已经读过。
不要添加样板式免责声明。当前提条件、限制或风险会改变读者应采取的行动时，应明确说明。不影响任何行动的免责声明只会训练读者忽略真正重要的那一条。
不要与虚构的替代方案作对比。在
```
X rather than Y
```
或
```
X instead of Y
```
中，只有当 Y 存在于草稿之外时才保留 Y。既有行为、真实 endpoint，或读者会遇到的 default，都符合这一条件。
```
Instead of returning a deck nobody asked for
```
提到了并不存在的代码。删除该分句，让 X 独立成立。
不要用分句告诉读者该如何权衡刚刚陈述的事实。删除该分句，看看是否丢失了信息。如果没有事实随之删除，该分句只是在为句子辩护。约束或后果属于事实，应予保留。替代方案也只在通过上述对比检查时保留。

修复清单发现的问题后，再次对照清单阅读修订稿，因为重写后的句子可能违反原句已经通过的规则。只有完整检查未发现任何问题时，才返回草稿。

如果完成这一轮检查后，草稿仍显得冗余、空泛或带有宣传意味，剩余问题就在词汇。对照 references/tells.md 检查。该文件列出每种模式及应采用的替代表达。

返回前，在本 skill 自己的目录中，对你修改过的文件运行

scripts/prose.mjs

。它会报告上述清单中可由 regex 判断的部分，并为每处命中给出文件和行号。需要 Node 22 或更高版本，或者 Bun，无需安装任何内容：

node <this skill's directory>/scripts/prose.mjs README.md docs/

默认情况下，它会报告 R-DOC-05 指定的 em dash、en dash、

--

、emoji、Title Case 标题，以及该规则列出的六个宣传性词语。

--house

会增加 house style 的其余检查，其中每处命中都需要你判断，而不是直接修复。

--length

会增加对超过 25 个词的句子的检查，并有意产生大量输出。只要报告了任何问题，它就会以状态码 1 退出。

该脚本会跳过 fenced blocks（围栏代码块）和 inline code，因此示例输出中引用的 dash 不会算作命中项。规则也可能用反引号标出它禁止的模式。它无法区分标题中的 proper noun 与普通的首字母大写词，因此标题被误报时，应传入术语文件并使用

--proper

，而不是重写标题。必需模板规定的标题应保持模板写法：出现命中项是预期行为，因此不要修改。

仅安装本 skill 的安装包也会包含该脚本，因为脚本位于此目录中。其他 skill 调用它时会检查脚本是否存在；若不存在，则自行读取相关文件。

若要在 CI 中而非草稿完成后执行相同规则，请参阅 references/linting.md。它将每条可检查规则映射到相应检查器，并列出无法由检查器判断的规则。

Do not touch

不要改动

Existing quoted code, error strings, log output, stack traces, and config samples: reproduce verbatim, including their dashes. This exception does not protect newly authored strings from review.
Another person's words in a quote or a review thread reply.
Identifier names, CLI flags, and file paths.
Required legal, license, and externally mandated security-advisory wording.
When editing prose a human wrote, fix only what is broken. Their voice is not a defect.

现有代码引用、错误字符串、日志输出、stack trace 和配置示例：逐字复现，包括其中的 dash。此例外不保护新编写的字符串，新字符串仍须接受审查。
引用中他人的话，或 review thread 回复中他人的话。
identifier 名称、CLI flags 和文件路径。
法律、license 和外部强制要求的 security advisory 措辞。
编辑人类撰写的文字时，只修复有问题的部分。个人表达风格不是缺陷。