Background Principles
The more complex the AI-generated content, the more important the output medium. The value of HTML lies in simultaneously improving information density, visual clarity, sharing convenience, and interactive capability: tables, SVG, CSS, code snippets, adjustable controls, copy and export buttons can let readers not just "finish reading," but compare, locate, adjust, review, and continue using. The purpose of Beautiful Article is to transform originally dull, linear, hard-to-digest text material into a single-file web article with a more beautiful visual experience, clearer reading rhythm, and easier review and sharing.
Boundaries (first determine whether this Skill should be used)
- The final main deliverable is single HTML article, not a web app.
- The article can have
Rawfree layer (any HTML / CSS / JS / React: interaction, layout and typography, motion, small tools, SVG / canvas diagrams as needed), butmust serve reading, explanation, argumentation, rhythm, or aesthetics。 - Do notgenerate: backend, forms, drag-and-drop workbenches, full dashboards, product prototypes, general-purpose Web Apps.
- Information density is confirmed by the user;by default retain 100% of the information, generating long-form web articles.
If what the user wants is an app rather than an article, stop and clarify; do not enter this Skill.
Workflow Overview
Phase 0 Intake 判断是否进入本 Skill + 初步文章类型
▼
Phase 1 Source → Markdown URL/PDF/DOCX/MD/文本 → source.md + extraction-notes.md
└ 主 Agent 内联 5 条 checklist 自查（仅复杂/低置信源升级 SubAgent）
▼
Phase 2 Editorial Planning 一份 plan.md（Brief / Outline / Theme / Assets 四段）
└ 主 Agent 内联自查（无 SubAgent、无 review 文件）
▼
Phase 3 Plan Checkpoint ★Checkpoint 1 必须停。逐项确认 5 件事：文章类型（含标配保留比例）/ 主题 / 版式 / 配图模式 / 封面
▼
Phase 4 First Spread 首屏 + 第一节 + 一个代表性视觉块（脚手架在此创建）
└ First Spread Reviewer SubAgent（写 review/first-spread-review.md）
└ ★Checkpoint 2 必须停。逐项确认 2 件事：验收结论 / 开发模式 A/B
▼
Phase 5 Full Article Build 生成完整网页文章（默认单 Agent，超长可按 Section 隔离）
└ Section Reviewer SubAgent（以消息返回 pass/fail，无须写 review 文件）
▼
Phase 6 Final Review Editorial / Visual / Technical 三视角终审（写 review/final-review.md）
▼
Phase 7 Repair 最小切片修复，有修复才写 repair-log.md
▼
Phase 8 Delivery ★Checkpoint 3 必须停。逐项确认交付决策 → 交付 article.html + 简短编辑说明
Workspace structure (created by scaffolding; these files are the Skill's long-term memory,do not rely only on chat context to remember decisions）：
<workspace>/
source/ original.* source.md source.<lang>.md(需翻译时) extraction-notes.md
plan/ plan.md # 单一规划文件：Brief / Outline / Theme / Assets 四段
article/ Cover.tsx(默认) Article.tsx sections/ raw-blocks/ assets/ article.html(产物)
review/ first-spread-review.md final-review.md # 仅这两份是常规产物
source-review.md(仅复杂源) repair-log.md(仅有修复时)
index.html package.json vite.config.ts tsconfig*.json (构建工装)
Hard Quality-Check Protocol (runs through the entire Skill)
The quality-check method differs by node — not all quality checks require starting a SubAgent, and not all quality checks require writing files. Mistakenly starting a SubAgent / mistakenly writing files is the primary performance problem; strictly follow the table below:
| Node | Quality-Check Method | Artifact | Why |
|---|---|---|---|
| Phase 1 Source (default) | Main Agent inline 5-item checklist | No file | The Main Agent has to read through source.md anyway |
| Phase 1 Source (complex/low-confidence sources only) | Source Reviewer SubAgent (against original.* diff） |
review/source-review.md |
Silent loss can only be caught by diff |
| Phase 2 Plan / before Checkpoint 1 | Main Agent inline self-check (starting a SubAgent is prohibited) | No file | The plan is a textual decision and 200-400 lines; the context is hot, and a SubAgent's cold start is actually slower |
| Phase 4 First Spread / before Checkpoint 2 | First Spread Reviewer SubAgent | review/first-spread-review.md |
The first screen sets the tone; one more independent pair of eyes is more reliable |
| Phase 5 Every Section | Section Reviewer SubAgent | Return pass/fail + fix points as a message (do not write files) | An article may have 5-15 sections; no one reads N review files again |
| Phase 6 Final Review / before Checkpoint 3 | Editorial + Visual + Technical Reviewer SubAgent | review/final-review.md |
Part of the deliverable; keeping it on file is valuable |
Iron rules:
- Plan Checkpoint (Phase 2 → Checkpoint 1): SubAgent is strictly forbidden for quality checks. After the main Agent finishes writing plan.md,on the spotcheck against the 5-item checklist (see the Plan self-check section in
references/review-checklist.md), revise per the conclusions inplan/plan.md，do not write any review file, then proceed to Checkpoint 1. - First Spread / Final must use a SubAgent (at these two nodes, SubAgent value > overhead); only when no SubAgent environment can be detected does the main Agent take over as fallback, and note at the top of the file "no SubAgent environment, main Agent taking over".
- Section Reviewer uses a SubAgent, butthe return value is a message(pass / fail + fix points); after the main Agent receives fail items it fixes them directly,do not have the SubAgent write the
review/section-NN-review.mdfile。 - Upon receiving any quality-check conclusion — first finish revising the output per the fail items, then report "done + self-check conclusion + what was changed". Reporting the raw conclusion directly without fixing = violation.
- Iron rule of decision collection · Never silently choose for the user: At every Checkpoint (1 / 2 / 3), all decision items requiring user confirmationmust each be listed independently + wait for the user's reply。Agent you may recommend("I recommend X, because ..."), but
you must not say "I've already decided X for you, let me know if it's wrong" — that is equivalent to depriving the user of the chance to choose.
- Preferred: if the environment has the
AskQuestiontool, make each decision item an independent question (one call can pass multiple questions), so the user can confirm item by item using selection cards. - Otherwise: stop and list all questions in the messagewith numbers(each question in its own paragraph, clearly stating the recommended option + rationale + alternatives), and explicitly say "I'll wait for your item-by-item reply before continuing",do not continue doing any follow-up work。
- Never: bundle multiple decisions into a single "choose all my recommendations / is everything OK?" yes/no question; nor default to proceeding to the next step after a "one-sentence recommendation".
- Preferred: if the environment has the
See the checklist and SubAgent prompt templates for each node in references/review-checklist.md。
File reading guide for each phase (progressive loading, don't read everything at once)
| Phase | Must read | Look up as needed |
|---|---|---|
| Phase 0 Intake | references/harness.md |
—— |
| Phase 1 Source→MD | references/source-to-markdown.md |
scripts/source-to-markdown-markitdown.py · scripts/source-to-markdown.py |
| Phase 2 Planning | references/article-types.md · references/information-density.md · references/plan-template.md · references/theme-selection.md · references/layout.md · references/asset-policy.md · references/cover.md(cover composition ideas) |
references/article-types/<type>.md · theme-profiles/*.md |
| Phase 4 First Spread / Phase 5 Build (review each section) | references/section-build.md · references/component-policy.md · references/raw-policy.md · Selected theme theme-profiles/<id>.md · Cover:references/cover.md |
references/scaffold.md(once when creating the project) · references/html-output.md |
| Phase 6/7 Review & Repair | references/review-checklist.md · references/repair-policy.md |
—— |
| Phase 8 Delivery | references/html-output.md |
references/pdf-output.md(only when the user chooses PDF export) |
In long sessions the agent easily forgets the principles — Phase 5 will repeatedly implement N Sections,review before starting each time
component-policy.md+raw-policy.md+ the current themetheme-profiles/<id>.md。
Phase 0 —— Intake
Determine whether to enter this Skill, and give a preliminary article type and output mode (default single HTML).
| What the user provides | What should be done |
|---|---|
| One or more materials (URL/PDF/DOCX/MD/text/screenshot) | Enter Phase 1 |
| Only says "help me make an X article" but has no materials | Ask back: Material or an outline is needed first. The Skill does not invent content out of thin air for the user. |
| What is clearly wanted is an app / tool / dashboard | Stop and clarify; do not enter this Skill |
Capture the target language:record at the outset the final article language the userexpects (e.g. if the user mentions "use Chinese / make an English version", etc.).
- The user specified a language → record it in
plan/plan.mdthe "Target Language" of the Brief section. If it differs from the source material's language, Phase 1 must first produce anatural-sounding translated versionof the source text, and subsequent writing is based on the translated version (see Phase 1). - The user did not specify → by defaultthe final article language follows the source material's language, with no translation.
Self-check: does the user want anarticleor aweb app? Is complete information needed? Should more material be requested first? Has the user specified a final language? Is it consistent with the source language?
Phase 1 —— Source → Markdown
Unify any input into source/source.md, and write uncertain items into source/extraction-notes.md.
For the rules and handling of various input types see references/source-to-markdown.md; you may use the
MarkItDown main path or a lightweight fallback script for PDF/DOCX/HTML extraction.
After writing to disk,the main Agent performs an inline self-check（references/source-to-markdown.md (the 5-item checklist of), fixes according to the conclusions,
then proceeds to Phase 2; extraction-notes.md only whenis marked as low-confidence / complex source original.* does it escalate to an independent Source Reviewer
SubAgent and perform a diff-style verification against review/source-review.md）。
Language handling (immediately after extraction): determine the language of source.md .
- The userdid not specifya target language, or the target languageis consistent with the source → do not translate; subsequently write directly based on
source.md, final article language = source language. - The userspecifieda target language andit is inconsistent with the source → first produce anatural-sounding translated version
source/source.<lang>.md(e.g.source.zh.md/source.en.md), as thefactual foundationfor subsequent Phase 2+; the original textsource.mdis retained for reference. Translation requirements:use natural target-language wording and remove translationese(restructure sentences according to the target language's expressive conventions, do not translate word for word, and leave no stiff foreign word order / stacked passives / foreign punctuation); terms / numbers / code / formulas / citations remain accurate, and the structure and information retention ratio stay unchanged. Write the translation notes intoextraction-notes.md。
Phase 2 —— Editorial Planning
form an editing plan,do not write HTML directly。produce only one plan/plan.md(four sections: Brief / Outline /
Theme / Assets); for the template see references/plan-template.md：
- Brief: target reader / article type / information retention ratio / must keep / may trim / tone / main points / reading goal / target language / layout width / TOC / image strategy.
- Outline: Hero / Lead / Summary / Section list / what information to keep in each section / whether each section needs Raw·Table·CodeBlock·Formula·Image / ending method.
- Theme: selected theme + rationale + conflict explanation (see
references/theme-selection.md）。 - Assets: Illustration strategy and per-image plan (see
references/asset-policy.md；nonemode, just write one sentence for this section).
For article type routing see references/article-types.md; for information density and component ratio see
references/information-density.md。
Self-check method · Hard constraint: after writing plan/plan.md , bythe main Agent inlinecheck against the 5-item Plan self-check checklist
(see references/review-checklist.md 's Plan self-check section), and after revising according to the conclusions, plan/plan.md，go directly to
Checkpoint 1; do not open a SubAgent, do not write review/plan-review.md。
Phase 3 —— Plan Checkpoint (★hard gate · Checkpoint 1, must stop)
Iron rule: never silently choose on the user's behalf. Each decision item must be listed independently and the user must be waited on for an independent answer.
You may recommend ("I recommend X, because …"),but you must notsay "I've already decided on X for you; tell me if it's wrong"—the latter is equivalent to smuggling in a default value and depriving the user of the chance to choose.
Collection method (choose one based on the environment):
- Prefer the
AskQuestiontool: pass each item as an independent question (multiple questions can be passed in one call), and the user confirms item by item with a selection card. - No
AskQuestiontool: stop and in the message list each question **with a number + in its own paragraph + clearly write the recommended option + reason- alternatives**, and explicitly say "I will wait for your item-by-item replies before continuing";do not continue doing any follow-up work。
Whichever method is used: eachindependent decisioncorresponds toone independent question，do not package them into a yes/no "are they all OK?"。
The 5 items that must be confirmed independently(none may be omitted):
| # | Decision item | Options (semantic labels · including the standard information retention ratio) | Notes |
|---|---|---|---|
| 1 | Article type(information retention ratio is bundled in) | Full-length article / archive longform · ~100% ／ research report / formal analysis full-report · ~80% ／ teaching steps / getting-started guide tutorial · ~90% ／ concept / system explanation explainer · ~80% ／ dialogue / interview / podcast dialogue · ~80% ／ PR / proposal / incident review review · ~70% ／ opinion / commentary / narrative essay · ~70% ／ interactive learning / fully understand a concept interactive-explainer · ~25% 原文摘录 + 75% AI 重构 ／ decision summary / for busy people briefing · ~50% ／ image-and-text focused / dissemination and display visual-essay · ~40% |
AI recommends one and writes a one-sentence reason.The ratio is already bound into the type options, so it is no longer a separate question (otherwise there would be longform + 20% such pseudo-combinations). If the user wants to deviate from the standard, use a one-sentence free-text override ("I want longform + 60%"); see "How to deviate from the standard" below |
| 2 | Theme | tufte / press / other registered themes (read theme-profiles/index.json） |
AI recommends one and writes a one-sentence reason |
| 3 | Layout width | narrow / regular / wide / full | AI recommends one; default regular |
| 4 | Illustration mode(required · "pass by default" is not allowed) | none / user-assets / placeholders / ai-generated | One sentence "only determines whether to use external Image；Raw is unaffected" |
| 5 | Cover(3:4 book-cover style feature image, positioned above the TOC + body text) | On (default) / Off | The AI recommends "On" and gives a one-line composition idea (which kind of key visual + which cover template A/B/C/D/E to choose).briefing / dialogue It may recommend "Off". See references/cover.md |
TOC is on by default: because it has only one switch + almost every article should have it on, it can be covered in the Plan Checkpoint opening explanation with the single sentence "TOC is on by default, tell me if you want it off,"and does not need to be a separate question。
Items that already use default values and do not need to be asked separately(you must still state "tell me if you want to change this" in the opening explanation, giving the user a chance to change their mind; it cannot be completely hidden):
- Final article language: follow the source language (unless the user has already specified it earlier / the translation is already complete).
- Whether editing may delete, trim, reorganize, and rewrite the tone: allowed by default (executed according to the information retention ratio above).
- Whether to see the first-screen sample first: will be done first by default (this is Phase 4).
- TOC: on by default.
If the user says "you decide" for the theme → take your first recommendation,but still list it alongside the other candidates in the options, marked "Default · AI Recommended," leaving room for the user to change their mind; you cannot just skip the theme question.
How to deviate from the "standard" information retention ratio: every article type comes with a recommended retention ratio (see the table above). In the vast
majority of cases, the standard is enough. If the user wants fine-tuning (for example, "longform but only 60%" → a heavily edited long article),
have the userwrite one sentence in the free text after the opening explanation"I want <type> + <X%>" to override it. After receiving the override, the AI must in
plan/plan.md the Brief section simultaneously record "type / standard retention / user override to X%," and remind the user that this is a "non-standard
combination" — such combinations require the main Agent to manually adjust the body/visual ratio when writing each section.
Plan Checkpoint opening message template (send a brief explanation before collecting decisions):
plan/plan.md 已经写好（自检通过）。我会逐项跟你确认 5 件事：文章类型 / 主题 / 版式宽度 /
配图模式 / 封面。
我的推荐先放在这里供参考（不会替你选）：
- 类型：<X>（含标配信息保留 <Y%>。理由：…）
- 主题：<theme>（理由：…）
- 版式宽度：<width>（理由：…）
- 配图模式：<策略>（理由：…）
- 封面：开 / 关（理由：…；若开，构图想法：…）
默认走但你可以推翻：语言跟随源语言；允许编辑删减重组；TOC 开；接下来会先做首屏样张。
信息保留比例如要偏离类型标配，下面回答完直接告诉我具体百分比（如 "longform 但只要 60%"）。
下面逐项请你确认。
After sending the explanation above,immediatelyuse AskQuestion to pass 5 questions (or, in an environment without tools, list the 5
questions by number, then stop and wait for replies). Only after receiving answers to all 5 itemsmay you proceed to Phase 4; if the user gave a "non-standard retention
ratio" in the free text, first confirm that the AI has recorded it in plan/plan.md before proceeding to Phase 4.
Phase 4 — First Spread (the article version of "first chapter acceptance")
First do "cover (if on) + first screen + first section + one representative visual block."The scaffold creates the workspace here：
# 默认开封面
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=<id>
# Checkpoint 1 用户选了"封面 · 关"
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=<id> --no-cover
bash <path-to-beautiful-article>/scripts/scaffold.sh --list-themes
It creates a Vite + React + TS workspace (installing from npm the reacticle latest published version) + source/ plan/ review/ memory directory + assembler article/Article.tsx + a sample section component
(+ default article/Cover.tsx, unless --no-cover). See references/scaffold.md。
First screen (Hero / Lead) written into assembler article/Article.tsx；The first Section must be written as a standalone component
article/sections/01-*.tsx(this is the code anchor for later parallelization, see references/section-build.md）。
Cover(if on) replaces article/Cover.tsx in <CoverPlaceholder /> with a text-image composition customized to the theme + article's main idea,the shell (3:4 container + print pagination) must not be changed. For cover design guidelines, see references/cover.md。
npm run dev Preview. It determines the title character / font size / content density / Raw style / image placement / whether the theme fits.
After the first Section is complete, create a First Spread Reviewer SubAgent according to the hard quality-check protocol, write
review/first-spread-review.md（including 5 self-checks for the cover, see references/cover.md), and after fixing,
proceed to Checkpoint 2.
Checkpoint 2 · First Spread (★hard gate, must stop)
Have the user review the first screen + first Section,and choose the subsequent development mode. The same iron rule for decision gathering as Checkpoint 1 also applies:two independent confirmations, bundling is forbidden; prefer AskQuestion, and if no tool is available, list them by number and stop to wait for a reply。
First send a short message:
首屏 + 第一个 Section 做好了，npm run dev 在 localhost 预览。
质检结论见 review/first-spread-review.md（已按 fail 项改完，列出修了哪些）。
下面两件事请你独立确认：1) 验收结论 2) 后续开发模式。
Then use AskQuestion to passtwo independent questions(or list the two questions by number and stop to wait for a reply):
- Review conclusion — options:
通过 · 进入完整生成/局部修改 · 我会另起一条说改哪里/主题或版式不合适 · 回到 Checkpoint 1。 - Subsequent development mode — options:
A · 单 Agent 顺序（默认 · 最稳 · 风格最统一）/B · 多 Agent 并行（最快 · 风格轻微差异）。
Do not bundle these two things into "pass + A, OK?" — the user may "pass the review but want to use B," or vice versa. After both questions have received replies, proceed to Phase 5.
Phase 5 —— Full Article Build
Generate the complete article according to the development mode selected at Checkpoint 2. See references/section-build.md +
references/component-policy.md + references/raw-policy.md。
Iron rule · Each Section must be an independent component file（article/sections/NN-*.tsx），It is strictly forbidden to write
multiple Sections directly into one component。article/Article.tsx is only assembler: import and order each
Section, owned by themain Agent. Large Raw blocks are likewise isolated into article/raw-blocks/NN-*.tsx. File-level isolation
is the prerequisite for multi-Agent parallelism.
Development mode (selected at Checkpoint 2):
- A · Single Agent sequential (default): the main Agent sequentially writes each
sections/NN-*.tsx, most stable, most consistent style. - B · Multi-Agent parallel: subagents eachown one
sections/NN-*.tsxfile and develop in parallel;the main Agent is responsible for merging and stability — maintain theArticle.tsximports and order, runnpm run typecheck/build, fallback theme and style consistency, resolve conflicts. For the subagent prompt template seereferences/section-build.md。
Other principles: the body text is the main subject; all Raw uses --ra-* theme tokens, wild styles are forbidden; 100% information retention is mainly based on long-form
structure, with Raw / images as enhancement; low information density may increase the proportion of visual blocks, but it must still be inarticle form。
After each Section is completemustfollow the hard quality-check protocol for Section Reviewer SubAgent: whether the outline task is completed / whether the information retention ratio is met / whether it connects with the preceding and following / whether it is over-componentized / whether there is enough body text / whether Raw and images have a clear purpose / whether this section's numbering is self-consistent.
The SubAgent returns pass/fail + fix points as a message(if pass, one line OK; if fail, list the fix points),do not write
review/section-NN-review.md files. After the main Agent receives fail items,directly fix the corresponding section file,
then report this section's delivery.
Phase 6 — Final Review (three-perspective final review)
Review from the reader / theme / technical three perspectives, produce review/final-review.md + repair list.
See the full hard checklist at references/review-checklist.md. Recommended three Reviewers (at least
one independent SubAgent when there are no Teams):
- Editorial Reviewer: article quality, information trade-offs, structure.
- Visual Reviewer: theme, Raw, images, mobile.
- Technical Reviewer: build, console, code / formulas, accessibility.
Core red lines: it is still an article (not an app) · information retention ratio matches the Plan · must-keep information is not lost · theme tone is consistent · Raw has no wild styles · no obvious AI flavor · readable on desktop + mobile · HTML can be built, opened, and shared.
Phase 7 —— Repair (smallest slice)
Repair at the smallest unit; rules see references/repair-policy.md。Forbidden: rewriting the whole article because of feedback on just one spot /
changing the already-confirmed article structure to fix visuals / deleting content the user specified must be kept in order to compress information.Write only if there are repairs
review/repair-log.md(if there are no repairs / it passes first try, do not write).
Checkpoint 3 · Final (★delivery confirmation)
After the final review is revised,stopand let the user independently confirm the delivery decision (do not skip straight to "I'm going to export HTML, if there's no problem then that's it"). Prefer AskQuestion; if there is no tool, list the questions with numbers in the message, stop, and wait for a reply.
- Delivery decision —— options:
通过 · 导出 HTML 交付/通过 · 同时导出 HTML + PDF/还有局部修复 · 我会列出具体修哪里/先停一停 · 我要再看看。
This is the only decision, butyou must still proactively stop and ask, do not silently go with the default HTML export.
Phase 8 —— Delivery
Build and deliver (commands see references/html-output.md）：
article/article.html(self-contained single page, CSS + JS inlined, can be opened offline) —— primary deliverable。- optional
article/article.pdf: generated only when at Checkpoint 3 the user chose "Pass · export both HTML + PDF". Command:
The script detects the chromium-family browser already installed on the system and injectsbash <path-to-beautiful-article>/scripts/html-to-pdf.sh@media printoverride (TOC collapses from a left-right grid into a top-bottom arrangement, TOC occupies the first page alone), headless printing. Zero npm dependencies. For detailed principles / troubleshooting seereferences/pdf-output.md。 - Brief editing note: article type / information retention ratio / theme / image strategy / main editorial trade-offs.
Default strategy
- Output single HTML; article type
longform; information retention 100%. - Language: if the userdoes not specify, thenfollow the source material language；; if specified and inconsistent with the source, then first produce a natural translation version
source/source.<lang>.mdand then write based on that (remove translationese, see Phase 1). - Theme: technical / evidence-first
tufte, narrative / commentary-firstpress(recommended based on the source material). - Layout: width defaults to
regular、TOC on by default(decoupled from the theme, seereferences/layout.md, all confirmed at the Checkpoint). - Images:Image mode is a required item at Checkpoint 1（
none/user-assets/placeholders/ai-generated), it only determines whether to use externalImage，Do not proactively generate AI images。 - Raw：orthogonal to images and always present by default, encouraged to be used more, but must serve specific paragraphs and use theme tokens. Choosing
nonedoes not affect Raw. - Self-check:Plan inline self-check (no SubAgent, no files)；First Spread and Final use SubAgent + write file； Section uses SubAgent + message return (no file written). See the "Hard Quality Check Protocol" section for details.
- Decision collection: Checkpoint 1 / 2 / 3 Each item confirmed independently · Never silently choose on the user's behalf. May recommend, but must not skip.
Prefer
AskQuestiontool (one independent question per item); if no tool is available, stop and list the questions by number for the user to answer. - Fix: minimum slice, write only if there is a fix
review/repair-log.md。 - Colophon · Cannot be removed: scaffold includes a colophon Raw block at the end of
article/Article.tsx(Made with [beautiful-article](github 仓库) · <主题> theme, low-contrast small text, theme token adaptive). Every article must retain it, deletion is prohibited, and it is prohibited to move it next to the Hero or float it into a corner. When switching themes, synchronously update the theme name +main.tsxin the colophon and the two places at<ThemeProvider theme="...">. - Cover · Enabled by default · Must combine text and image: scaffold by default creates in
article/Cover.tsxaScreen 3:4 + PDF dedicated first pagebook-cover-style hero image shell + placeholder (--no-coveroff). The cover is above the TOC + Hero + body text, and exists independently. During Phase 4 First Spread, the main Agent replaces<CoverPlaceholder />with a custom image + text composition based on the theme + the article's core message .Hard constraints: the shell ratio / print pagination cannot be changed, there must be visual elements- text, use only
--ra-*token, no remote images, do not repeat Hero content.Visual technique fully open: SVG / CSS / Canvas / complex React components / any mix is chosen by the Agent; as long as it works well. See details inreferences/cover.md(including 5 self-checks + 5 composition templates + cover starting points for each theme). PDF export will automatically make the cover occupy the first page exclusively, with the TOC starting from the second page.
- text, use only
- PDF export · Optional: the main deliverable is always
article/article.html。only when Checkpoint 3 the user selected "Pass · Also export HTML + PDF", only then runbash <skill>/scripts/html-to-pdf.shto generatearticle/article.pdf; if not selected, do not act. Do not export by default on the user's behalf. See details inreferences/pdf-output.md。
Success criteria
- Itis first and foremost an article。
- The final article language matches user intent (unspecified = follow the source language; specified = the whole text is unified into the target language, idiomatic, without translationese, without residual source-language fragments).
- The user-confirmed information density is respected; key content from the source material is not accidentally lost.
- The theme's character is unified; both illustrations and Raw serve reading.
- The page is more worth reading than Markdown; the HTML can be opened and shared directly.
- At 40% information, it reads like an edited article, not a shrunken summary; at 100% information, it reads like a finely polished long-form piece, not a transcription of the original text.
Related resources (annotated by "when to read")
| File | When to read | Content |
|---|---|---|
references/harness.md |
Phase 0 | The Skill's harness perspective, six questions, state file conventions |
references/source-to-markdown.md |
Phase 1 | Various inputs → source.md rules, extraction self-check, script usage |
references/article-types.md |
Phase 2 | Article type routing overview (with per-type links) |
references/article-types/<type>.md |
Phase 2 after type selection | Single-type structure / components / Raw boundaries / illustration tendencies / self-check |
references/information-density.md |
Phase 2 | Information density levels, relationship with components / visual proportions |
references/plan-template.md |
Phase 2 | Single plan/plan.md template (four sections: Brief / Outline / Theme / Assets) and how to write it |
references/theme-selection.md |
Phase 2 | Theme selection, decoupling of density and theme, constraints for adding new themes |
references/layout.md |
Phase 2 / Checkpoint | Layout: width mode (decoupled from theme) + TOC, confirmation and usage |
references/asset-policy.md |
Phase 2 | Four sources of illustrations, AI illustration prompt principles, image self-check |
references/cover.md |
Phase 2 / Phase 4 when writing the cover | Book-cover-style cover design guide (screen 3:4 / PDF exclusive first page): hard constraints, fully open visual techniques, composition templates, cover starting points for each theme, 5 self-checks |
references/section-build.md |
Phase 4/5 | One file per section iron rule, single/multi-Agent modes, parallel subagent prompt, main Agent merging |
references/component-policy.md |
Phase 4/5 each section | reacticle component protocol, prose-first, information density and component proportions |
references/raw-policy.md |
Phase 4/5 each section | Raw allowed / forbidden, token-driven, Raw self-check |
references/html-output.md |
At build / delivery time | dev / build / single-file HTML commands and artifacts |
references/pdf-output.md |
Phase 8 Delivery when the user chooses PDF export | html-to-pdf.sh usage, TOC layout principles, how Raw appears in PDF, troubleshooting |
references/review-checklist.md |
Phase 6 | Reviewer checklists and prompt templates for each phase |
references/repair-policy.md |
Phase 7 | Minimal slice fix reference table |
references/scaffold.md |
Phase 4 when creating a project | What the scaffold does, usage, workspace structure, switching themes |
theme-profiles/index.json + *.md |
Phase 2 theme selection / Phase 5 writing | Theme authoring profile (for AI to read, not CSS) |
scripts/scaffold.sh |
Phase 4 run once | One-click creation of an article workspace |
scripts/html-to-pdf.sh |
Phase 8 Delivery only when the user chooses PDF | HTML → PDF (headless browser + injected print CSS, zero npm dependencies) |
scripts/pdf-print-overrides.css |
When modifying PDF styles | html-to-pdf.sh injected into <head> the @media print overrides: A) TOC collapses into vertical stacking; B) pagination behavior (undo .ra-section atomization, no orphaned headings, widow/orphan control, etc.); C) cover occupies the exclusive first page |
scripts/source-to-markdown-markitdown.py |
Phase 1 | MarkItDown main path, suitable for complex PDF / DOCX / HTML |
scripts/source-to-markdown.py |
Phase 1 | Lightweight fallback, suitable for Markdown / TXT / simple HTML or when MarkItDown is unavailable |