agent-skills/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

同步 think-twice v3 与 teach-me v2

Browse Source 
think-twice 的 double-check.md 和 self-contain.md 已并回正文,副本里同步删除,现在只剩 SKILL.md 和 style.md。

teach-me 换成 v2:用途改为对接上下文,结构换成带出口条件的动作式步骤,不再依赖 think-twice 的文件。

README 里"只装 teach-me 会让指针掉空"的警告已经不成立,改成两者各自完整、互相交接。表格里两条描述一并更新。
This commit is contained in:
im0o
2026-08-20 23:43:40 +08:00
parent 6b2e167e69
commit 96450e2335
6 changed files with 358 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -5
View File
@@ -13,15 +13,16 @@ npx skills add ssh://gitea/agent-skills/skills
| 组 | skill | 做什么 | 平台 |
|---|---|---|---|
| Writing Clarity | `think-twice` | 重写一段输出,让它脱离上下文也能读懂,并且每条声明都经过验证 | 任意 |
| Writing Clarity | `teach-me` | 逐层讲一个主题,每轮一层,由用户决定什么时候进下一层 | 任意 |
| Writing Clarity | `think-twice` | 重写一段输出,让它脱离上下文也能读懂,每条声明都经过验证,不留只在写作过程中有意义的内容 | 任意 |
| Writing Clarity | `teach-me` | 对接上下文:长任务跑完、隔久回到旧项目、面对陌生代码时,先自己探索,再一轮讲一层 | 任意 |
| Windows Tools | `disk-master` | 只读扫描磁盘占用,解释盘为什么满了,生成可交互 HTML 报告 | Windows |
| Windows Tools | `everything-file-search` | 借 Everything 的 IPC 按文件名和路径极快定位文件 | Windows,需要 Everything 在跑 |
| Image To Data | `baimiao-table-ocr` | 表格截图转 CSV / JSON / Markdown / XLSX | 任意,需要网络 |
`think-twice` 和 `teach-me` 放同一组不是为了好看。`teach-me` 的 SKILL.md 直接引用
`think-twice` 目录下的 `double-check.md`、`self-contain.md`、`style.md`,只装
`teach-me` 会让这三个指针掉空。它每个指针都带了内联兜底说明,但拿到的是简写版。
`think-twice` 和 `teach-me` 各自完整,单独装任何一个都能用,不存在跨 skill 的文件
依赖。放同一组是因为它们互相交接:`think-twice` 重写一次仍然没打中的时候转给
`teach-me`,`teach-me` 遇到会活得比对话久的内容时交给 `think-twice` 过一遍。两个都
装上,这两条路才通。
`baimiao-table-ocr` 会把图片上传到第三方服务。隐私敏感的图不要用它。
skills/teach-me/SKILL.md
+150 -57
View File
@@ -1,73 +1,166 @@
---
name: teach-me
description: >
Walk the user through something until they actually understand it — layer by
layer, one round at a time, every claim verified before it is taught. Use
when the user asks to be walked through a design, codebase, requirement, or
decision ("讲懂我", "给我讲讲", "teach me"), or wants to understand what
exists from what was built. Also fires on handover from the think-twice
skill after a second miss (a rewrite already failed).
Bring a present reader from "I do not have the context" to "I understand
this", one layer per round, by exploring the subject yourself first and
verifying every claim before you teach it. Use when the user asks to be
walked through a design, a codebase, a decision, or what an agent did on a
long task ("讲懂我", "给我讲讲", "walk me through"); when they are returning
to their own work after a long gap; when they are meeting an unfamiliar
project; or on handover from think-twice after a re-aim at a higher level
still missed.
---
# Teach Me
The user is present and can talk back: teaching is a loop, not a lecture. The
goal is their understanding, confirmed by them — never declared by you. An
explainer that re-explains everything, announces the matter settled, and
changes the subject has failed, even if every sentence was true.
The user is present and can talk back, so this is a loop and not a lecture.
Their understanding is the goal, and only they can confirm it. An explainer
that covers everything, declares the matter settled and moves on has failed,
even where every sentence was true.
The rule files referenced below — `double-check.md`, `self-contain.md`,
`style.md` — are parts of the **think-twice** skill; find them in that
skill's own directory. Where think-twice is not installed, the inline clause
at each pointer carries the rule's core.
## What it is for
## Loop
Context transfer. The context exists somewhere and the user does not have it.
An agent ran a long task and they need to know what came of it. They are
returning to their own project after months away. The project is not theirs at
all, and somebody has to go read it before it can be explained.
1. **Map and slice.** Build context from zero — the user starts as a **cold
reader**: assume no earlier names or interfaces remembered. Split the subject into layers, ordered so each
layer stands on the one before it. One layer per round.
2. **Check yourself before you teach.** Every claim in the layer follows
`double-check.md` from the think-twice skill: verify it
(read the code, run the command, open the source) or label it uncertain.
When the stakes warrant, spawn a context-free subagent to blind-check a
claim. Never teach a guess.
3. **Teach one layer.** Settled things are stated directly — not re-opened as
questions. Express under `self-contain.md` from the think-twice skill: every
term glossed at first use, examples drawn from material the conversation
already holds — real files, real numbers, the user's own work — before any
abstraction. Teach the subject, not the method: this skill's own vocabulary
(layers, gates, loop) never appears in what the user reads. Chinese prose
for a human reader also follows `style.md` from the think-twice skill:
plain sentences over bold-label bullets, bold at most twice per paragraph,
no filler connectives, no emoji.
4. **Route real decisions only.** Put to the user only what changes behavior,
scope, or a public interface; digest implementation detail yourself. When a
proper decision interview emerges, hand over to the grilling skill where
installed; otherwise ask the decisions yourself, one per message, each with
a recommended answer.
5. **The user gates the loop.** A round ends with one line — 这段讲了：plus a
one-clause recap — then stop. No question attached, no preview of what
comes next: the user's natural reply is the gate. Advance on "懂了"; stay
on anything else. Never ask "clear?" — it gets a polite yes, and politeness
is not information. On "没懂": first locate the stuck point — one question,
with candidate options so answering is cheap (options belong here and only
here) — then re-teach that same layer from a different angle: a concrete
scenario walked start to end, a contrast with the thing it is most often
confused with, the technical terms reattached last. Never change the subject
yourself — when the user changes it, follow them, and pick the layer back
They are short of context, not of intelligence. Never ask them to remember, to
go look something up, or to explain their own project back to you.
## Two inversions
The **grilling** skill interrogates the user until a design is settled. This
skill runs the same machine backwards: it interrogates itself, on their behalf,
until they are oriented.
- **Grill yourself, not the user.** Ask the questions they would ask if they
already knew enough to ask them, then go and answer those questions.
- **Finding out is your job.** Every fact you need, you fetch. A question you
would have to put to the user is a question you have not done the work on
yet.
## The loop
### 1. Go find out first
Read the code, the history, the task transcript, the files. Dispatch a subagent
for anything wide, and do not block on it: only the layers that depend on a
running search wait for it.
Never teach a guess. A claim goes in verified, or it goes in carrying an
explicit "I have not checked this". Where verification is impossible from here,
say what is unknown and what would settle it.
**Complete when:** nothing you are about to say rests on a guess, and no
remaining unknown would change the shape of the story.
### 2. Slice it into layers
Order them so each layer stands on what has already been taught. The first
layer is whatever makes the rest make sense, which is usually why the thing
exists and what breaks without it. It is almost never the file tree.
Keep the ordering live. What the user asks reshapes it.
**Complete when:** the next layer depends on nothing the user has not already
been told.
### 3. Grill yourself on this layer
Before teaching it, put the user's questions to it yourself. Why does this
exist? What breaks without it? How is it different from the thing it is most
often confused with? How do you know? Anything you cannot answer sends you back
to step 1.
**Complete when:** for every sentence in the layer, you can say why they should
believe it.
### 4. Teach the layer
Settled things are stated, not re-opened as questions.
Two axes set the altitude. **Access** is what they can open right now;
**background** is what they already know. Someone who owns the repository but
has never read it can open everything and still needs the design rather than
the schema. Pitch one level above what feels right and let them pull you down.
Gloss every term at first use. Quote in the original and put the reader's
language right after it. Say what the thing is, not what somebody earlier
guessed wrong about it.
Length is part of teaching, not a separate concern. A layer that runs three
screens was two layers.
This skill's own vocabulary — layers, rounds, exploring — never appears in what
the user reads. Teach the subject.
**Complete when:** the layer stands on its own and can be read in one pass.
### 5. Close the round with a divider, and fix where you are
End the prose, put in a divider, and add a short block that leaves the reader
able to say three things: what is being covered, what this layer concluded, and
what comes next.
The third one is what makes continuing feel worth it. A reader who cannot tell
whether the end is near has no reason to stay.
Field names, layout, and whether to show progress are yours to choose each
round. Two rounds that look identical mean you stopped thinking.
The final round closes differently: recap the whole path, layer by layer,
conclusion first, then ask what is still open.
**Complete when:** the reader can answer all three without scrolling up.
### 6. Read what comes back, then move
No confirmation is required and "got it" is never requested. Asking "is that
clear?" buys a polite yes, and politeness is not information. Any reply is a
signal:
- They follow the thread you left, so teach the next layer.
- They ask about something else, so follow them there and pick the layer back
up when they return.
- They say they are lost, so find the stuck point first with one cheap question
that offers candidates, then re-teach that same layer from another angle: a
scenario walked start to finish, or a contrast with whatever it gets confused
with, technical terms reattached last.
- A real decision surfaces, so put it to them one at a time, each with a
recommended answer, and only where it changes behaviour, scope or an
interface. Digest implementation detail yourself. Where **grilling** is
installed and a full interview is warranted, hand over to it.
The final round closes differently: a short summary of everything taught,
conclusion first — not a completion announcement.
**Complete when:** they say they have it, or say it is enough. Your own
judgement that the matter is settled does not end the loop.
## Done when
## A round ending, filled in
The user says they understand, or says it is enough. Nothing else ends the
loop — not your own judgement that the matter is settled.
```
…(the layer itself)
## Out of scope
---
Now Why the rules ended up in one file (layer 2 of about 5)
So far Splitting them out made following them optional, and did not
make the file smaller
Next Which rules genuinely do belong somewhere else
```
Multi-session curriculum learning (workspace, lessons, learning records) is
the `teach` skill, where installed. Rewriting one outgoing text is
`think-twice`. This skill is the live loop that gets a present user from
"没懂" to "懂了".
The shape above is one round's answer, not a form to fill in.
## Working with other skills
**think-twice**, where installed, owns the rules for prose that has to stand
alone; run a layer through it when that layer will outlive the conversation.
Nothing here depends on it being present.
**grilling** takes over when the session turns from explaining into deciding.
**teach**, where installed, owns multi-session curriculum work with its own
workspace and records. This skill is one live session.
## Boundary
Rewriting a single outgoing text is think-twice. This skill is the live loop
that gets a present reader from lost to oriented.
skills/think-twice/SKILL.md
+153 -57
View File
@@ -1,77 +1,173 @@
---
name: think-twice
description: >
Rebuild output so a reader with only this text can understand or act, with
every claim verified. Use when the user doesn't understand your last
output, asks to expand / explain / rewrite plainly / make it
self-contained; when shipping prose that must stand alone (handoff,
PR/issue body, doc, subagent brief); or when another skill needs a clarity
or evidence pass.
Rebuild an outgoing text so a reader holding only it can understand or act,
with every claim verified and nothing left in it that only mattered along the
way. Use when the user says they do not understand, asks to expand / explain /
rewrite plainly / make it self-contained; when shipping prose that must stand
alone (handoff, PR or issue body, doc, subagent brief, summary of a system);
or when another skill needs a clarity or evidence pass.
---
# Think Twice
Do not polish the last draft with more jargon. Rebuild from **only what will
appear in the output you send**, on two pillars:
Do not polish the last draft. Rebuild it from only what will appear in the text
you send.
- **Self-contained** — the words work alone for the **cold reader**: someone
with this text and only what is guaranteed in front of them. Rules in
[self-contain.md](self-contain.md).
- **Double-checked** — every claim in them is verified or labeled. Rules in
[double-check.md](double-check.md).
Three questions decide every rule below. A rule that answers none of them does
not belong here, however good the writing advice.
Skip trivial one-liners the user already follows.
- **Can they parse it?** The reader hits a word or a pointer they cannot
resolve, and the paragraph stops.
- **Is it true?** They read it, act on it, and reality does not match.
- **How much of it survives?** They open it a week later and have to wade
through what only mattered while it was being written.
## Second miss
A text can pass one and fail the others. Verification comes first: fluent
invention does more damage than clumsy truth.
A rewrite already shipped and they still don't get it, or ask the same
question in other words → invoke the **teach-me** skill (needs a reader who
can talk back); never a third rewrite. Where teach-me is not installed, do the
minimum it would: locate the stuck point with one question, then re-explain
that point through a concrete example.
One case skips the whole process: a throwaway one-line instruction the user has
already acted on, or already knew. Do not rewrite it and do not verify it.
## The reader
Two axes, and using only one of them is the common failure. **Access** is what
they can open right now. **Background** is what they already know.
| | knows the domain | does not |
|--------------------|-------------------------------|-----------------------------------------------------|
| can open the code | exact locations, code, schema | the design one level up; code as an optional anchor |
| cannot | conclusion and boundaries | consequences and comparisons |
The table is a default, not a verdict. A reader in the top-left cell who is
optimising for speed may still want the design level and no code at all. When
it is unclear, one direct question is faster than a guess.
Pitch one level higher than feels natural and let them ask downward. Opening
with code or a schema is a choice that needs a reason: they asked for it, or
they have quoted it themselves.
The **cold reader** holds this text plus whatever is guaranteed in front of them
at the moment they read it, and nothing else. Assume that moment is a week from
now and the conversation is gone. An LLM cold reader is worse off than a human:
it does not error on an undefined reference, it silently invents a plausible
meaning for it.
## Process
1. **Diagnose** — one primary blocker: **concept** | **scope** | **steps**
| **token** (undefined word or dangling reference). Fix the highest one
first. For proactive prose where no one is stuck yet, diagnose the blocker
the reader is most likely to hit.
2. **Three questions**, answered silently: what does the reader have right now
(default: the cold reader)? Can they understand or act from that
alone? Which facts must the text pin — conclusion, scope, evidence, next
step?
3. **Double-check** — verify every claim the text will make, per
[double-check.md](double-check.md).
4. **Rebuild — do not patch.** Substance order: conclusion → what it is in
plain terms → in/out of scope when partial work matters → evidence when
trust matters → minimal path when action matters (success shape; on
failure, the next move, not only an error name). Every line obeys
[self-contain.md](self-contain.md).
5. **Deliver.** Match the shape to the reader and the scene. Only two rules are
fixed: conclusion first, and drop anything that does not change
understanding or action. For a chat reply to a person, short is the
default. This draft shape is scaffolding, not a mould; use it, reshape it,
or discard it:
### 1. Locate the blocker
1. **Takeaway** — 1–3 sentences
2. **Need-to-know** — only terms blocking this message (omit if none)
3. **Next step** — only if boundaries or action matter
Pick the highest one: **level** (pitched at the wrong altitude) | **concept** |
**scope** | **steps** | **token** (undefined word or dangling pointer). Then
name which conclusion, boundary, evidence and next step this text must carry.
The slots name the substance and its order, not literal headings — they can
be plain sentences. Chinese prose for a human reader additionally loads
[style.md](style.md), an optional part.
**Done when:** one blocker is named and every load-bearing slot is listed.
## Done when
### 2. Fill, then verify
- [ ] Passes the [self-contain.md](self-contain.md) final check
- [ ] Passes the [double-check.md](double-check.md) final check
- [ ] Conclusion first; everything left changes understanding or action
- [ ] Chinese human-facing output: every [style.md](style.md) rule swept, rule
by rule
- [ ] A second miss went to teach-me — or, where it is not installed, to its
minimum — not a third rewrite
Two jobs, and the second does not cover the first.
## Out of scope
**Fill** — go find the facts that belong in the text and are not in the draft
yet. A draft that never mentions a thing raises no alarm on its own, so nothing
downstream will catch the omission.
This skill rebuilds the words; tracker/PR mechanics (linking, closing,
labels) belong to whatever process owns them.
**Verify** — every claim already drafted gets checked against its source: read
the file, run the command, open the page. Where verification is impossible from
here, write what is unknown and what would resolve it.
**Done when:** no load-bearing fact is missing, guessed, or unlabeled.
### 3. Rebuild, do not patch
Order: conclusion, then what it is in plain observable terms, then in and out of
scope where partial work could be misread, then evidence where trust matters,
then the minimal path where action matters, including the success shape and the
next move on failure.
**Done when:** every line obeys the rules below.
### 4. Deliver
Conclusion first, always. Short is the default for a person reading in chat.
Go long only when the artifact itself is long-form (a handoff, a PR or issue
body, a doc), or the user asked for detail, or the load-bearing facts do not fit
without changing meaning. When it has to be long, put the body in a file and
keep the chat message short.
**Done when:** a reader holding only this can say what it means, how far it
goes, and what to do next, wherever those questions matter.
## Rules
### Can they parse it
- **No dangling references.** Undefined unless the body supplies them: "as
discussed", "per the design", "as usual", "as you mentioned", "see above".
Same for a private path or id used as the only source of a required fact.
Restate the fact, or give a locator **and** what to take from it.
- **Gloss on first use.** Acronyms, nicknames, codenames, internal shorthand:
one clause, at the first appearance, nowhere else.
- **One term, one meaning.** A thing keeps its name for the whole text; a
synonym halfway through reads as a second thing.
- **Mechanism, then name.** What they can see or do comes first; the internal
label second.
- **Define before you label.** Why it matters, what it does and does not do,
then the name for it.
- **Pin partial work.** What this does, what it deliberately does not, and
whether the larger goal is finished or only advanced.
- **Quote in the original, gloss in the reader's language.** A verbatim quote is
evidence; an untranslated one is a wall.
### Is it true
- **Verified or labeled.** Evidence you actually checked, or an explicit
"unverified". Never a guess in a conclusion's voice.
- **Evidence is concrete.** The file and line, the command and its real output,
the exact quote. "I checked" is not evidence.
- **Quotes carry attribution.** A decision, constraint or priority is quoted
verbatim, in its original wording, with who said it and when. A paraphrase
presented as fact turns a reversible decision into a law of physics.
- **Fact and judgement stay visibly apart.** A verifiable fact gets checked.
Someone's decision gets attributed.
- **Predict, then look.** Write the expected result before reading the actual
one. Matching afterwards is back-fitting, and the output would have
"confirmed" whatever you wrote.
- **Work already run is evidence.** Copy its real output instead of re-running,
which can repeat side effects. Predict-then-look still applies to it.
### How much survives
- **Cut the path you took.** The reader needs the decision and the shortest
route to it, not the dead ends. Evidence attaches to a claim; it is never
narrated as history. Test: if a sentence needs "first, then, and it turned
out" to stand up, it is process, so cut it.
- **Say what it is, not what it is not.** A negation earns its place only if the
reader would arrive at that wrong idea on their own. "This script does not
delete files" is a boundary and stays. "Not used as an SSH jump host", written
only because someone in the conversation had guessed wrong, is a correction
scar and goes. Delete the sentence and check whether the misreading comes
back.
- **Date everything that moves.** Absolute dates, never "last week". Drop "now",
"currently" and "just", or pin the moment they refer to. A pointer to
something that changes, such as a branch head or a running process, is marked
as a snapshot.
- **Drop whatever does not change understanding or action.**
- **No appendix for safety.** Length is not thoroughness.
### Chinese prose for a human reader
Also load [style.md](style.md), the only conditional part of this skill.
## When the rewrite misses
They still do not get it, or ask the same thing in different words. Diagnose
**level** before anything else: the usual cause is prose pitched below the
reader, and the fix is one re-aim higher, not a handover. A miss that survives
that goes to the **teach-me** skill, which needs a reader who can talk back.
Never a third rewrite.
## Boundary
This skill governs the words. Tracker links, close keywords and PR mechanics
belong to whatever process owns them.
skills/think-twice/double-check.md
-36
View File
@@ -1,36 +0,0 @@
# Double-check — the claims hold
A claim that reaches the reader unverified is a guess wearing a conclusion's
clothes. The first mismatch the reader finds costs the whole text its credit.
## Rules
- **Verified or labeled.** Every claim either carries evidence you actually
checked — code read, command run, file opened, source quoted — or an
explicit uncertainty label ("unverified", "low confidence, no repro").
Never write a guess in a conclusion's voice.
- **Evidence is concrete.** The file and line, the command and its real
output, the exact quote. "I checked" is not evidence.
- **Quotes are evidence.** A decision, constraint, or priority is quoted
verbatim, in its original language, with who said it and when. A paraphrase
is your judgement of their words; presented as fact, it turns a reversible
decision into a law of physics for the reader.
- **Fact vs judgement.** A verifiable fact gets checked. Someone's decision
gets attributed. Keep the two visibly distinct in the text.
- **Pre-commit, then look.** When a claim can be tested (a command, a check),
write the expected result before looking at the actual one. Matching after
the fact is **back-fitting** — the output would have "confirmed" whatever
you wrote.
- **Already-run work is evidence.** Something executed earlier in this session
proved itself then — copy its real output; re-running can repeat side
effects. Pre-commit still applies: write the success condition from the
step's original goal before inspecting that old output, or you are
back-fitting.
- **Blocked legwork is stated, not papered over.** If verification is
impossible from here, write what is unknown, why, and what would resolve
it. That sentence is itself the label.
## Final check
Strip every sentence you could not defend if the reader asked "how do you
know?". What survives is the text.
skills/think-twice/self-contain.md
-34
View File
@@ -1,34 +0,0 @@
# Self-contain — the words work alone
The **cold reader** has only this text, plus whatever is guaranteed to be in
front of them at the moment they read it. Every reference must resolve inside
that set. An LLM cold reader is worse off than a human: it does not error on
an undefined reference — it silently invents a plausible meaning for it.
## Rules
- **No dangling references.** Undefined unless the body supplies them: "as
discussed", "per the design", "as usual"; "see above" with no findable
target; a private path or id as the *only* source of a required fact.
Restate the fact, or give a resolvable locator **and** what to take from it.
- **Gloss on first use.** Acronyms, nicknames, codenames, team shorthand — one
clause, at the first appearance, nowhere else.
- **One term, one meaning.** A thing keeps its name for the whole text; a
synonym midway reads as a second thing.
- **Mechanism → observable consequence.** What the reader can see or do, not
internal names first. Plain words first; technical name second.
- **Define before you label.** Why it matters → what it does and does not do →
this text's scope. The label comes after the reader can already picture it.
- **Pin partial work.** What this can do, what it deliberately does not,
whether a larger goal is finished or only advanced.
- **Match detail to what the reader can use.** If they have only the text, put
boundaries and failure next-moves in the text. If they can open or run
things, say exactly how.
- **Examples fit the reader.** Output that ships beyond this conversation gets
generic, domain-neutral examples. Inside a conversation, the reader's own
material is shared context and the best example there is.
## Final check
Hand the text to the cold reader. If they must ask "what is X / how far does
this go / what's out / what next?", not done.
skills/think-twice/style.md
+48 -14
View File
@@ -1,18 +1,52 @@
# Style — 中文表述 (optional part)
Load only when the output is Chinese prose for a human reader; even then,
skip code-heavy text. This file is a guardrail against model-flavoured
prose; when model writing no longer needs it, delete the file and every
pointer to it (grep both skills for style.md) — neither core depends on it.
Load only when the output is Chinese prose for a human reader; even then, skip
code-heavy text. This file is a guardrail against model-flavoured prose; when
model writing no longer needs it, delete the file and every pointer to it (grep
both skills for style.md) — neither core depends on it.
Every rule is countable. Before delivery, sweep the list once: each rule
passes, or the text changes until it does.
Every rule is countable. Before delivery, sweep the list once: each rule passes,
or the text changes until it does.
1. **删空转连接词**：此外 / 然而 / 值得注意的是 / 需要指出的是。句子没了它们照样成立。
2. **删填充开场**：为了实现这一目标 → 为了这一点；在这个时间点 → 现在；系统具有处理的能力 → 系统可以处理。
3. **禁 `**小标题：** 一句话` 式 bullet 列表**。每项都以加粗标签加冒号开头的列表是模型腔；写成句子。（输出文档里操作步骤内的字段标签，如「操作：」「预期结果：」，是结构，保留。）
4. **禁强行三段式**。三个并列项逐个做删除测试：删掉后不改变动作、判断或风险的，删。两项或四项都正常。
5. **加粗每段最多两处**。加粗是"读者不能错过"，多了等于没有。
6. **连续三句同长，破一句**。
7. **删中文破折号（——）**，改逗号或句号。
8. **无 emoji**。
## 句子
1. **成分要齐**。主谓宾缺一个就重写。"一段文字可以过掉其中一个"，宾语是什么、
"一个"指什么，都没说，改成"一段文字可能通过了其中一问"。
2. **代词不留空**。"这三个"而不是"三个"，"另外两问"而不是"另外两个"。指代如果
要读者往回翻才能确定，就把名词写回去。
3. **不把动词当名词用**。"读者撞上一个解析不了的指代"里的"指代"是名词化，改成
"读者遇到一个理解不了的词"。
4. **一句一个意思**。一句里塞了两件事就拆成两句，长句拆行，不靠逗号串。
5. **连续三句同长，破一句**。
## 用词
6. **不用黑话**。判据是把这个词单独拿给没参与过对话的人看，他能不能懂。"入库"
"正本""落点"都不合格，写成"放进仓库""正式版""实现"。
7. **抽象比喻换直白**。"两个轴"写成"两个互相独立的维度"，"挑最高的那个"写成
"挑最该先解决的那个"。
8. **英文术语原词在前，中文解释跟在括号里**。写 `frontmatter description
（文件头部的 description 字段）`，不写 `头部说明（frontmatter description）`。
引用整段英文原文时，紧接着给一句中文释义。
9. **删空转连接词**：此外 / 然而 / 值得注意的是 / 需要指出的是。句子没了它们
照样成立。
10. **删填充开场**：为了实现这一目标 → 为了这一点；在这个时间点 → 现在；
系统具有处理的能力 → 系统可以处理。
## 篇幅
11. **宁可多几个字，也不压缩到读不懂**。"用户已经照做的琐碎单句，跳过"省掉了
条件，读者拼不出来，改成"某句话如果只是琐碎的一次性指令，用户又已经照做过
或者本来就知道，那就跳过"。
12. **禁强行三段式**。三个并列项逐个做删除测试：删掉后不改变动作、判断或风险
的，删。两项或者四项都正常。
13. **加粗每段最多两处**。加粗是"读者不能错过"，多了等于没有。
14. **禁 `**小标题：** 一句话` 式 bullet 列表**。每项都以加粗标签加冒号开头的
列表是模型腔，写成句子。（输出文档里操作步骤内的字段标签，比如「操作：」
「预期结果：」，是结构，保留。）
## 符号
15. **标点跟语境走**。中文语境用全角：，。（）：；英文语境用半角：`,.():`。
一句中文里嵌英文术语或者代码，术语本身按英文写，包住它的标点仍是全角。
16. **无 emoji**。