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
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.