By default, deliver a systematic textbook exceeding 40 pages (>40), fully explaining prerequisite knowledge and mechanisms, with a complete set of cases, exercises, and appendices. The actual page count is subject to the compiled PDF; do not pad pages with blank space or repetitive content; when the user specifies a length, their requirement takes precedence.
A long-form course aimed at beginners starting from zero: provide analogies only for difficult points, keep the main text in a restrained university lecture tone, and deliver as a compilable PDF.
What problem does this skill solve
The three most common mistakes when writing hardcore technical long-form articles:
- Assuming the reader has background knowledge— right from the start it's "attention mechanism," "$\mathrm{SE}(3)$ equivariance," "diffusion models," and high school students (as well as smart people from other fields) are lost by page 3;
- Cramming an entire article into one giant .tex— by line 800 the context blows up, the structure spirals out of control, and changing one place requires reading through the entire text;
- Repeatedly stepping into compilation pitfalls——
equationline breaks in,\textttlong DOI overflow, pseudocode package wrong environment... every article requires debugging all over again.
This skill solidifies theworkflow, teaching standards, and hard compilation constraintsthat have already been validated on 4 articles, so that new articles go directly into "writing content" instead of "adjusting formatting."
I. Delivery Standards (Hard Metrics)
| Dimension | Standard |
|---|---|
| Length | Exceeding 40 pages (>40)(A4, usually 42--50 pages, continuing to expand according to topic depth; subject to the actual measured page count of the compiled PDF) |
| Reader | Assume only a high school education, do not assume any domain background |
| Assembly | Main file + parts/ volume directory + \input |
| Compilation | tectonic passes in one go,zero fatal errors, significant Overfull (≥10pt) cleared to zero |
| Analogy density | Throughout the text, 15--25"life analogy" boxes,covering only difficult concepts, and allowingmultiple difficult points to be packaged together after being explainedin one box (one box may contain 2--4 scenarios) |
| Appendix | Must includethe four-piece set: step-by-step mathematics / glossary quick reference / self-test questions and answers / DOI literature list (if the topic involves papers) |
II. Workflow (Volume-Based Pipeline)
① 定角度 → ② 建任务清单 → ③ 建 parts 目录 → ④ 逐 part 写
→ ⑤ 主文件 \input 拼装 → ⑥ tectonic 编译 + 自修复 → ⑦ 交付
① Define the angle: ask first, then write
Topics are often broad ("AI4S," "world models," "embodied intelligence VLA").Writing in the wrong direction = a dozen pages wasted, so before starting to write, use AskUserQuestion to lock in one angle, provide 3--4 options, put the recommended one first and mark it "(recommended)."
Principles for the recommended order:Preferentially choose the thread that complements existing articles and has the strongest mathematical/storytelling quality。
②③ Create tasks and directory
mkdir -p <文章目录>/<主题>_parts
Using TaskCreate create 2--3 tasks: write long-form article / compile and self-repair / (optional) verify hand-calculated numbers.
④ Write part by part (the core rhythm of this skill)
One Write call per part, 250--320 lines. Do not try to finish 2000 lines in one go.
Recommended volume split (6 parts):
| File | Content | Target line count |
|---|---|---|
p1_basics |
Chapter 0 opening + the 2--3 most foundational prerequisite concepts | ~250 |
p2_<核心对象> |
What the subject protagonist is and what problem it solves | ~290 |
p3_<方法/工具> |
Toolbox and methodology | ~230 |
p4_mechanism |
Mechanism details, decomposed layer by layer | ~290 |
p5_handson |
Hand calculations + runnable code | ~220 |
p6_frontier |
Panoramic comparison, pitfalls, appendix four-piece set | ~320 |
⑤ Assemble the main file
The main file only contains preamble + table of contents + a series of \input,no body text(see assets/latex-template.tex)。
⑥ Compile and self-repair
cd <文章目录> && tectonic -X compile <主文件>.tex --outdir . > /tmp/x.log 2>&1; echo "EXIT=$?"
grep -E "Missing \\\$|Undefined control|! LaTeX|! Package|Giving up|unrecoverable|Runaway" /tmp/x.log
grep "Overfull" /tmp/x.log | grep -vE "\([0-9]\.[0-9]+pt|\([0-9]pt\)" # 筛出 ≥10pt 的显著溢出
Page count check: PDFs use compressed object streams, grep cannot find them, need to decompress and count:
import re, zlib
data = open("<主文件>.pdf", "rb").read()
c = 0
for m in re.finditer(rb'stream\r?\n(.*?)\r?\nendstream', data, re.S):
try: dec = zlib.decompress(m.group(1))
except: continue
if b'/Type' in dec and b'Page' in dec:
c += len(re.findall(rb'/Type\s*/Page\b(?!s)', dec))
print("pages:", c)
III. Teaching standards (this is the key to "a high school student can understand it")
1. Analogies cover only difficult points, and can appear bundled together (2026-08-29 revision)
Principle A: Analogies are a scarce resource, give them only to genuinely difficult concepts. Readers are at high school level; many concepts themselves do not constitute an understanding barrier (such as "degrees of freedom = the number that can vary independently" "coordinate system = a method of describing position"), such concepts can be defined in one or two plain sentences,do notgive an analogy box. Analogy boxes are reserved only for those difficult points where "without an analogy it is hard to grasp the intuition", for example: curse of dimensionality/explosion of degrees of freedom, underactuation and tendon-driven actuation, error accumulation, action chunking, diffusion denoising, Markov property, sparse rewards, discount factor, exploration vs exploitation, PPO small-step updates, domain randomization, friction cone, Kalman filtering, contact discontinuity. The test standard:Would a high school student be confused when seeing this concept for the first time? If not confused, it does not deserve an analogy box.
Principle B: After explaining several difficult points, bundle the analogies together once. Do not have an analogy box follow each difficult point (otherwise the whole text is interrupted by orange boxes, poor rhythm). The correct rhythm is: after explaining 2--4 difficult points in succession, use one tipbox(internally using numbering or paragraphs) to give the life analogies for these difficult points all at once. For example, after explaining the three methods of imitation learning (behavior cloning/action chunking/diffusion), use one "imitation learning trio" box: the parrot game (error accumulation), reciting a whole passage of text (action chunking), playing a snowflake photo in reverse (diffusion denoising). Readers can compare the three concepts laterally in one reading, which is more effective than three scattered boxes. Multiple scenarios in the same box should be clearly labeled "Scenario 1/Scenario 2/Scenario 3" or separated into paragraphs, to prevent confusion.
Principle C: tipbox titles must be calm content phrases or imagery, meta-descriptions are forbidden (2026-08-29 revision). Titles should be vivid noun phrases like "Parrot, reciting text, and snowflake photos" "Hold the cup steady, close your eyes and touch your nose" "The moment the fingertip presses against the tabletop", like subheadings in a lecture note.ForbiddenMeta-descriptions like "Life analogy · X" or "Focused analogy · X (N difficulties packaged in one go)" that expose the writing strategy—"packaging" and "analogy" are the author's actions, not the content, and readers can tell at a glance that this is an AI writing habit. Likewise, self-explanations such as "we will package the analogies together" or "a bonus section" are prohibited in the main text.
A verified, useful analogy library (can be reused directly or used as a style reference for creating new ones):
| Abstract concept | Analogy |
|---|---|
| Atoms/chemical bonds | Lego bricks and connection points |
| Principle of minimum energy | A ball rolling downhill / standing is more tiring than sitting |
| Activation energy | Climbing over a mountain vs going through a tunnel |
| Shape determines function | Key and lock |
| Combinatorial explosion of conformational search | How long it takes to try every combination (10^{18} times the age of the universe) |
| Homology modeling | Copying homework (collapses when there is no similar problem type) |
| Co-evolution signals | A two-person dance (if one raises a hand, the other must turn) |
| Triangle inequality | Can three sticks form a triangle? |
| Equivariance | Looking at a map (rotate the map: distances stay the same, coordinates rotate with it) |
| Gradient descent | Going down a mountain blindfolded |
| Attention Q/K/V | Picking someone up at a train station (your own criteria / each person holding a sign / what they carry) |
| Diffusion models | Turn a photo into snowflakes, then learn to play it in reverse |
| Inverse folding | Building according to blueprints; de novo design = being your own designer |
| Self-consistency check | Putting architectural drawings into a computer for structural simulation |
| QM/MM partitioning | Repairing a watch: use a magnifying glass on the movement, hold the watch case in your hand |
| Link atoms | Putting caps on a cut water pipe |
| Three types of embedding | Whether there is an outlet in the room / whether a magnet is affecting you |
| The functional debate | Two scales calibrated differently, weighing two bags of rice of similar weight |
| Two-state reactivity TSR | Two mountain paths at similar heights, with a small trail connecting them in the middle, and you can still switch paths |
| Quantum tunneling | Climbing over a mountain vs passing directly through the mountain body |
| Radical clock | Put a pursuer with a known speed nearby, and infer the athlete's time in reverse |
| Source of selectivity | Whether the hand can reach is more critical than whether the line is thin |
| Proton transfer (Grotthuss) | Passing buckets to fight a fire |
| Uncoupling | A coordination failure causing leaks of water or electricity |
2. From simple to complex, defeat them one by one
- The main text uses onlymiddle school to high schoolmathematics (Pythagorean theorem, quadratic equations, exponents);
- Allhardcore content such as group theory, manifolds, variational inference, ELBO, etc. is put intoAppendix "Step 2", and the main text clearly marks "can be skipped on first reading";
- At the end of each part (part), there must be
\begin{stepbox}{本篇小结(你已会什么)}, use bullets to list the capabilities delivered in this installment, and hook the reader with "In the next installment we will…".
3. Chapter 0 must provide a "map of the whole book"
Use a numbered list to explain installment by installment "what this installment solves, and what you will be able to do after reading it," so readers know the route before they start.
4. Tone: Stanford lecture-notes style (revised 2026-08-29)
The overall tone should be like the lecture notes of a Stanford CS course (the handouts for CS229 / CS231n / CS224n):calm, restrained, professional. The test: read any paragraph to a smart high-school student, and he should feel "this is a serious textbook teaching me," not "an AI is lecturing me."
Prohibited list (AI-speak / meta-narration / colloquialism):
- Self-explanations of writing strategy—sentences that talk about "how the author himself writes," such as "we will bundle the analogies together," "three hard points bundled at once," "a bonus section," "no extravagance or waste," "next let us look at," "it is worth mentioning," etc., must all be deleted or rewritten as the content itself;
- label prefixes such as "Life analogy ·" and "Bundled analogy ·" (Principle C);
- colloquial exclamations and stock phrases—"easy to remember," "you may be curious," "exactly," "it is just that simple";
- redundant connectives—"it should be noted that" should be deleted whenever possible;
- abuse of dashes—consecutive multiple "——" parallel structures should be changed to declarative sentences.
Allowed: cross-references ("Chapter X will elaborate"), optional annotations ("you may skip this on a first reading"), calm transitional sentences ("let us look at an example first," "explain it clearly in five steps"). Titles must all use content phrases or images (Principle C).
5. Numbers in hand-calculation chapters must actually have been calculated
For any chapter that claims to be a "hand calculation," first compute the numbers in Python before writing them into the article;it is forbidden to write numbers by feel. Only verified numbers (such as $k=1400\ \mathrm{s^{-1}} \Rightarrow \Delta G^{\ddagger}\approx13.2$ kcal/mol) may be written into the main text.
IV. The four-piece appendix set (none may be missing)
- Appendix A · Ladder 0→1→2: Ladder 0, three-sentence intuition / Ladder 1, hand-calculation closed loop / Ladder 2, rigorous mathematical formulation (including definitions of groups and equivariance, diffusion on manifolds, transition state theory and tunneling corrections, etc.).
- Appendix B · Glossary for quick reference:
p{3.0cm}p{8.6cm}A two-column table, 25--35 entries, each explained in one sentence. - Appendix C · Self-test questions and answers: 8--10 questions, with complete reference answers.
- Appendix D · List of verified DOI references: divided by topic into 2--5 tables (see the discipline in the next section).
V. DOI / citation discipline (the defense line against academic flaws)
When the user explicitly requires DOIs to be attached, never write DOIs from memory—getting them wrong is an academic flaw.
- Before starting to write, use
WebSearchverify item by itemthe DOIs of the key references; - conveniently collect other already verified DOIs on the same topic from the search results (the reference lists of review articles are a gold mine);
- at the beginning of the article, use
tipboxto declare: "All reference DOIs cited in this article have been verified online item by item (verification date: YYYY-MM-DD), and are summarized in Appendix D.Any entry for which this article does not give a DOI is unverified; readers should check it themselves before citing it.」 - Typesetting must use a line-breakable, clickable form (see compile constraints in the next section).
6. Compilation hard constraints (a blood-and-tears checklist accumulated from 4 articles)
Every one of the following has actually caused compilation failure or layout overflow. Follow them directly when writing code; do not wait for an error.
Fatal level (causes XeTeX to crash, no PDF produced)
| # | Pitfall | Correct approach |
|---|---|---|
| 1 | Math symbols used bare in body text (e.g., 向量场\approx常数) |
must be wrapped in $...$ Within |
| 2 | File names/code identifiers'underscoreswritten in body text (e.g., vla_flow_matching) |
\texttt{vla\_flow\_matching}; for long words also add \- breakpoint |
| 3 | pseudocode commands wrapped in tcolorbox |
must \begin{algorithm} + \begin{algorithmic}[1], the box can only contain the algorithmoutside |
| 4 | algpseudocode use all uppercase algorithmic style |
Use mixed case:\Require \Ensure \State \Repeat \Until \For \EndFor |
| 5 | Use \TO |
This package is undefined; write \For{$i=0$ \textbf{to} $N-1$} |
| 6 | Appendix use \section*{附录…} |
Use \appendix, thereafter \section automatically becomes A/B/C |
| 17 | Body text usesbackticksto wrap code identifiers (e.g., `no_slip`) |
In body text, a backtick is just a quotation character; when it contains _ it reports Missing $; always write \texttt{no\_slip}(underscores must be escaped) |
Overflow level (not fatal but text runs off the page)
| # | Pitfall | Correct approach |
|---|---|---|
| 7 | Multi-line equations written into equation |
equation does not support line breaks; switch to align + \nonumber(previously overflowed by 94pt) |
| 8 | Oversized \texttt{...} cannot break lines |
Use \- to insert breakpoints;Long DOI/URL directly use \href{https://doi.org/<DOI>}{\nolinkurl{<DOI>}} |
| 9 | Narrow p{} column holds long DOI |
DOI column given ≥5.9cm;\texttt switch to \nolinkurl can reduce from 27 Overfull to 6 and all <10pt |
| 10 | Table total width exceeds the text block | Three-column budget:0.8 + 7.9 + 5.9 = 14.6cm(text block 16cm), column width including \tabcolsep should leave margin |
| 18 | Long tabular spanning pages(e.g., 40-row glossary) |
Spanning pages produces Overfull \vbox (measured 19.5pt); split by topic into 2 tables, each ≤25 rows |
TikZ level
| # | Pitfall | Correct approach |
|---|---|---|
| 11 | Side-by-side subfigures use xshift + outer scale |
The combination of the two miscalculates positions, causinggraphic overlap; change toOverlay display in the same coordinate system |
| 12 | \foreach with gray!55!white / above left=4pt |
Occasionally TikZ parsing fails; switch to explicit \draw sequence + gray!50 / above left |
| 13 | position the title text separately outside the box | Write the title and body text inthe same node's {} inside, with text width to prevent going out of bounds |
| 14 | Node coordinates exceed ±5 (x)/±3 (y) | With scale=0.9 Control, estimate the total width first before writing |
| 19 | In polar coordinate parameters use \def macros (such as +(\ttone:0.9)、arc (0:\ttone:0.9)) |
occasional Undefined control sequence(\ttone cannot be expanded in polar coordinates); write coordinates/angles directly as numbers or wrap them with {...} package |
content-level
| # | pitfalls | correct approach |
|---|---|---|
| 15 | Chinese text appears garbled (e.g. "要知??药物") | Before delivery grep -n "��" scan once |
| 16 | Claims the code "can run directly" but the local machine doesn't have the dependencies installed | local machineno torch/numpy; either write it asrunnable with pure standard library, or clearly label it "reference implementation, requires pip install torch」——Do not falsely claim it has been verified |
VII. Code chapter principles
- Prefer pure standard library Python(
mathis sufficient), so that on the local machineactually run it onceverify the output, and in the article you can honestly say "verified by actual run"; - if PyTorch must be used, label it "reference implementation (requires
pip install torch), not actually run", and explain line by line what the code is doing (explain the approach, not the syntax); - After the code there must beline-by-line explanationandexpected output description。
VIII. Pre-delivery self-check list
- Does the compiled PDF actually exceed 40 pages? (If the user has other length requirements, follow the user's requirements)
-
EXIT=0, with noUndefined control/Missing $/Giving up? - significant Overfull (≥10pt) cleared to zero?
- no Chinese garbling (
grep "��")? - analogy boxes 15--25?covers only difficult points, canbe packaged together(one box 2--4 difficult points)? Is there a summary at the end of each article?
- simple concepts (intuitive concepts such as degrees of freedom, coordinate systems, torque, etc.)notoveruse analogy boxes?
- Are the four appendix items complete?
- Have all DOIs been verified, and is the
\nolinkurlline-breakable form used? - Have hand-calculated numbers been verified with Python?
- Is the code either runnable (pure standard library) or labeled as not run?
IX. Structural baseline
The following items are only used to align structure and length, and do not depend on external directories on the author's machine:
| Article | Page count | Features |
|---|---|---|
| AI4S protein structure design textbook | 47 | 6 parts, appendix includes glossary and self-test questions; complete PDF see repository assets/samples/pdfs/ |
cyp450_qmmm_masterclass.tex |
42 | 6 part + cyp450_parts/,24 verified DOIs, pure standard library runnable code |
ai4s_protein_design_masterclass.tex |
14 | Single-file version (old style), can serve as a negative reference |
../university-textbook/ |
— | Companion skill: leans toward LaTeX/top-conference pseudocode standards; this skill leans toward "popular-science long-form + volume assembly" |
Directory conventions
generated_content/
├── <主题>_masterclass.tex # 主文件(仅 preamble + \tableofcontents + \input 列表)
├── <主题>_parts/ # 分卷目录
│ ├── p1_basics.tex
│ ├── p2_xxx.tex
│ └── ...
└── <主题>_masterclass.pdf # tectonic 产物
X. Two traps in acceptance metrics (measured on the 8th article, 2026-08-29, be sure to follow)
Trap one: number density will be inflated by TikZ coordinates and code blocks
Directly using "proportion of digits in body-text characters" as a dehydration metric will be seriously misleading: TikZ diagrams are full of (-3.4, 1.1)、minimum width=2.6cm
such coordinates and dimensions,The more figures, the higher the density appears. Measured on the same article: with TikZ the density is 7.00%, and after stripping tikzpicture only 3.69% remains.
Correct measurement method (always use this for acceptance): after stripping tipbox/stepbox/exbox/thinkbox + lstlisting + tikzpicture + tabular
, then count the character count and digit ratio of the remaining "pure narrative text".
| Article | Density with figure code | Pure narrative density (correct metric) |
|---|---|---|
| Protein article (positive-review benchmark) | 3.67% | 3.15% |
| DNA v1 (rollback) | 4.35% | 2.86% |
| DNA v2 | 4.21% | 1.77% |
| DNA v3 | 7.00% | 3.69% |
Baseline: pure narrative density 3–4%(below 2% the narrative is too empty, above 5% it is piling up numbers). Hand-calculation/code chapters are allowed to spike to 10%+ on their own; that is due to the chapter itself and is not counted in the overall total.
Trap two: the real source of the "sense of substance" is the pure narrative character count, not the total page count
Illustrations willcrowd out prose length. Measured: the protein article has 38355 pure narrative characters / 5 figures; DNA v3 has 23515 pure narrative characters / 11 figures, yet the page counts are similar (47 vs 48).The "substance" readers subjectively perceive comes from the pure narrative character count.
Baseline: pure narrative ≥30000 characters (target 35000+). When too many figures cause insufficient pure narrative, the correct approach is toadd narrative paragraphs(historical stories, process stories, case walkthroughs), not to delete figures— too many figures is never the problem; "figures with no words" is.
Appendix: code verification caught another bug (reiterating that you must actually run it)
sum(p * log2(p/0.25) for p in probs if p > 0) in probs when it is a dict will report an error
TypeError: '>' not supported between 'str' and 'int'——iterating a dict yields keys, not values, you must write probs.values()。
Code claimed to run must actually be run once before being written into the article.
Quantitative results for each article in this series (for aligning with the baseline, not as objects to imitate)
| Article | Pages | Figures | Tables | Analogies (number/box) | Summaries (number/box) | Pure narrative character count | Pure narrative density |
|---|---|---|---|---|---|---|---|
| Protein (positive-review benchmark) | 47 | 5 | 2 | 46 (3.3) | 9 (7.8) | 38355 | 3.15% |
| GRN Neural ODE | 42 | 3 | — | — | — | — | — |
| CYP450 QM/MM | 42 | 3 | — | — | — | — | — |
| Personal finance primer | 48 | 1 | 12 | — | — | — | — |
| Mendicant monk (humanities) | 44 | — | — | — | — | — | — |
| DNA v1 (rollback) | 42 | 1 | 12 | 37 (5.2) | 5 (41.6) | 30291 | 2.86% |
| DNA v2 | 39 | 5 | 6 | 61 (1.6) | 6 (0.5) | 31786 | 1.77% |
| DNA v3 | 48 | 11 | 5 | 73 (0.9) | 15 (2.0) | 23515 | 3.69% |
Can only serve as a quantitative baseline, never as an object to imitate—only align the numbers; always create the content anew yourself.
Supporting resources
- Before formal writing, read the writing guide。
- When mechanism diagrams, flowcharts, or TikZ figures are needed, read the diagram guide。
- When creating the main file, reuse the LaTeX template。
- Before compiling and delivering, read the LaTeX checklist。
These files all belong to this skill and must be kept together with SKILL.md during installation.