ConardLi/garden-skills

Beautiful Article

Background & Principles

The more complex AI-generated content becomes, the more important the output medium is. HTML's value lies in simultaneously increasing information density, visual clarity, shareability, and interactive capability: tables, SVGs, CSS, code snippets, adjustable controls, copy and export buttons—allowing readers not just to "finish reading" but to compare, locate, adjust, review, and continue using the content. The purpose of Beautiful Article is to convert originally dry, linear, and hard-to-digest written materials into a single-file web article that offers a richer visual experience, a clearer reading rhythm, and is easier to review and share.

Boundaries (First, Determine if This Skill Should Be Invoked)

• The final primary output is a single HTML article, not a web application.
• The article may include a Raw free layer (any HTML/CSS/JS/React: interactivity, layout, typography, animations, widgets, on-demand SVG/canvas diagrams), but it must serve reading, explanation, argumentation, rhythm, or aesthetics.
• Do not generate: backends, forms, drag-and-drop workbenches, full dashboards, product prototypes, general-purpose web apps.
• Information density is confirmed by the user; default is 100% information retention, producing a long-form web article.

If what the user wants is an application, not an article, pause to clarify and do not enter this Skill.

---

Workflow Overview

Phase 0  Intake            Decide whether this skill applies + preliminary article type
   ▼
Phase 1  Source → Markdown  URL/PDF/DOCX/MD/text → source.md + extraction-notes.md
         └ Main Agent inline 5-item checklist self-check (only complex/low-confidence sources upgrade to SubAgent)
   ▼
Phase 2  Editorial Planning One plan.md (Brief / Outline / Theme / Assets sections)
         └ Main Agent inline self-check (no SubAgent, no review file)
   ▼
Phase 3  Plan Checkpoint   ★ Checkpoint 1: MUST STOP. Confirm 5 items: article type (with default retention ratio), theme, layout width, illustration mode, cover
   ▼
Phase 4  First Spread      First screen + first section + one representative visual block (scaffold created here)
         └ First Spread Reviewer SubAgent (writes review/first-spread-review.md)
         └ ★ Checkpoint 2: MUST STOP. Confirm 2 items: acceptance conclusion, development mode A/B
   ▼
Phase 5  Full Article Build Generate complete web article (default single agent, can be section-isolated for very long content)
         └ Section Reviewer SubAgent (returns pass/fail as a message; no review file needed)
   ▼
Phase 6  Final Review      Three-perspective final review: Editorial / Visual / Technical (writes review/final-review.md)
   ▼
Phase 7  Repair            Minimal chunk repair; only write repair-log.md if repairs were made
   ▼
Phase 8  Delivery          ★ Checkpoint 3: MUST STOP. Confirm delivery decision → deliver article.html + brief editorial note

Workspace structure (created by scaffolding; these files are the Skill's long-term memory, do not rely solely on chat context for decisions):

<workspace>/
  source/   original.*  source.md  source.<lang>.md(if translation needed)  extraction-notes.md
  plan/     plan.md                                    # Single planning file: Brief / Outline / Theme / Assets
  article/  Cover.tsx(default)  Article.tsx  sections/  raw-blocks/  assets/  article.html(output)
  review/   first-spread-review.md  final-review.md   # Only these two are regular outputs
            source-review.md(only for complex sources)  repair-log.md(only if repairs were made)
  index.html  package.json  vite.config.ts  tsconfig*.json   (build tooling)

---

Mandatory Quality Inspection Protocol (Throughout the Skill)

Inspection method differs by node—not all inspections require a SubAgent, and not all require writing a file. Unnecessary SubAgent/sub-file creation is the primary performance issue; follow the table strictly:

Node	Inspection Method	Output	Rationale
Phase 1 Source (default)	Main Agent inline 5-item checklist	No file	Main Agent will read source.md anyway
Phase 1 Source (only complex/low-confidence)	Source Reviewer SubAgent (compared against original.* diff)	review/source-review.md	Silent omissions are only detectable via diff
Phase 2 Plan / Before Checkpoint 1	Main Agent inline self-check (FORBID SubAgent)	No file	Plan is a text-based decision 200-400 lines; context is hot; SubAgent cold start is slower
Phase 4 First Spread / Before Checkpoint 2	First Spread Reviewer SubAgent	review/first-spread-review.md	First screen sets the tone; an independent second set of eyes is more reliable
Phase 5 Each Section	Section Reviewer SubAgent	Return pass/fail + fix points via message (do NOT write a file)	An article may have 5-15 sections; N review files go unread
Phase 6 Final Review / Before Checkpoint 3	Editorial + Visual + Technical Reviewer SubAgent	review/final-review.md	Part of the deliverable; worth archiving

Hard Rules:

1. Plan Checkpoint (Phase 2 → Checkpoint 1) is STRICTLY FORBIDDEN to use a SubAgent for inspection. After the Main Agent writes plan.md, it in-place checks against the 5-item checklist (see the Plan self-check section of references/review-checklist.md), revises plan/plan.md based on findings, and does NOT write any review file, then proceeds to Checkpoint 1.
2. First Spread / Final Review MUST use SubAgents (the value of SubAgents at these nodes exceeds the overhead); only if a SubAgent environment is unavailable should the Main Agent act as a fallback, noting "No SubAgent environment; Main Agent fallback" at the top of the file.
3. Section Reviewer uses a SubAgent, but the return value is a message (pass/fail + fix points); the Main Agent directly fixes any fail items on receiving them, do NOT have the SubAgent write a review/section-NN-review.md file.
4. Upon receiving any inspection conclusion: fix all fail items in the output FIRST, then report "Done + self-check result + what was fixed". Reporting the raw conclusion without fixing is a violation.
5. Hard Rule for Decision Gathering: Forbid silent user choices. At each Checkpoint (1/2/3), all decision items requiring user confirmation MUST be listed independently + await user response. The Agent may recommend ("I recommend X because…"), but must NOT say "I've already set X for you; tell me if it's wrong" — this deprives the user of choice.
   • Prefer: If the environment has an AskQuestion tool, submit each decision item as an independent question (multiple questions can be passed in a single call), allowing the user to confirm each via selection cards.
   • Otherwise: Pause and list all questions with numbers in the message (each question in its own paragraph, clearly state the recommendation + rationale + alternatives), explicitly say "I'll wait for your answers to proceed", do not continue any further work.
   • NEVER: Package multiple decisions into a single "Agree with all recommendations?" yes/no question, or proceed directly to the next step after a single recommendation sentence.

Checklist and SubAgent prompt templates for each node are in references/review-checklist.md.

---

Progressive File Reading Guide (Read incrementally; don't read everything at once)

Phase	Must Read	Reference on Demand
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 before 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 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 if user chooses PDF export)

In long conversations, agents tend to forget principles — During Phase 5, which implements N sections repeatedly, re-read component-policy.md + raw-policy.md + the current theme theme-profiles/<id>.md before starting each section.

---

Phase 0 — Intake

Determine if this skill applies; give a preliminary article type and output mode (default: single HTML).

What the User Provides	What to Do
One or more materials (URL/PDF/DOCX/MD/text/screenshot)	Proceed to Phase 1
Only says "Help me create an article about X" but provides no materials	Ask back: Request materials or an outline first. The skill does not imagine content for the user out of thin air
Clearly wants an application / tool / dashboard	Pause to clarify; do not enter this skill

Capture target language: At the outset, record the user's desired final article language (e.g., if the user says "write in Chinese" or "make an English version").

• User specifies a language → Record it in the Brief section of plan/plan.md as "target language". If it differs from the source material language, Phase 1 must first produce a natural-sounding translated version of the source, and subsequent phases work from this translated version (see Phase 1).
• User does not specify → Default to final article language matches source material language; no translation.

Self-check: Is the user asking for an article or a web application? Does it require complete information? Should you first request more materials? Did the user specify the final language? Is it consistent with the source language?

---

Phase 1 — Source → Markdown

Normalize any input into source/source.md. Write uncertainties into source/extraction-notes.md. Rules and handling of various inputs are detailed in references/source-to-markdown.md; you may use the MarkItDown main path or a lightweight fallback script for PDF/DOCX/HTML extraction.

After saving, perform a Main Agent inline self-check (the 5-item checklist in references/source-to-markdown.md), make any necessary corrections, and then proceed to Phase 2; only if extraction-notes.md marks the source as low-confidence/complex, escalate to an independent Source Reviewer SubAgent to perform a diff-based check against original.* (write review/source-review.md).

Language handling (immediately after extraction): Determine the language of source.md.

• User did not specify a target language, or target language matches source → No translation; subsequent work is based directly on source.md; final article language = source language.
• User specified a target language different from source → First produce a natural-sounding translated version source/source.<lang>.md (e.g., source.zh.md / source.en.md) as the factual foundation for subsequent Phases 2+; keep the original source.md for reference. Translation requirements: Use natural target language expressions, avoid translationese (reorganize sentences according to target language conventions, do not translate word-for-word, avoid awkward foreign word order / passive stacking / foreign punctuation), keep technical terms / numbers / code / formulas / quotations accurate, maintain structure and information retention ratio. Write translation notes into extraction-notes.md.

---

Phase 2 — Editorial Planning

Formulate the editorial plan; do not write HTML yet. Produce only one file: plan/plan.md (four sections: Brief / Outline / Theme / Assets). Template in references/plan-template.md:

• Brief: Target readers / article type / information retention ratio / mandatory items / optional cuts / tone / main argument(s) / reading goal / target language / layout width / TOC / illustration strategy.
• Outline: Hero / Lead / Summary / Section list / what information to retain per section / whether each section needs Raw·Table·CodeBlock·Formula·Image / closing style.
• Theme: Selected theme + rationale + conflict notes (see references/theme-selection.md).
• Assets: Illustration strategy and per-image plan (see references/asset-policy.md; for none mode, one sentence suffices).

Article type routing in references/article-types.md; information density and component ratios in references/information-density.md.

Self-check mode — Strong constraint: After writing plan/plan.md, the Main Agent performs an inline self-check against the 5-item Plan checklist (see the Plan self-check section of references/review-checklist.md), revises plan/plan.md based on findings, and directly proceeds to Checkpoint 1. It is FORBIDDEN to open a SubAgent or write review/plan-review.md.

---

Phase 3 — Plan Checkpoint (★ Hard Node · Checkpoint 1: MUST STOP)

Hard rule: Forbid silent user choices. Each decision item must be listed independently and await user response independently.

You may recommend ("I recommend X because…"), but must NOT say "I've already set X for you; let me know if it's wrong" — the latter sneaks in a default and deprives the user of choice.

Collection method (choose based on environment):

• Prefer AskQuestion tool: Pass each item as an independent question (multiple questions can be passed in a single call); the user confirms each via selection cards.
• No AskQuestion tool: Pause, and in a message list each question with a number + one independent paragraph + clearly state the recommendation + rationale + alternatives, explicitly say "I'll wait for your answers on each item before continuing", do NOT proceed with any subsequent work.

Regardless of method: Each independent decision corresponds to one independent question, do NOT package into a single "Everything OK?" yes/no.

5 items that MUST be confirmed independently (all required):

#	Decision Item	Options (Semantic Labels · Including Default Info Retention Ratio)	Notes
1	Article type (info retention ratio is bundled in)	full-length article / archive: longform · ~100% ∕ research report / formal analysis: full-report · ~80% ∕ tutorial / 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 / playing with a concept: interactive-explainer · ~25% original excerpts + 75% AI reconstitution ∕ decision summary / for busy readers: briefing · ~50% ∕ visual-focused / promotional display: visual-essay · ~40%	AI recommends one with a one-line rationale. Ratio is already tied to the type option; do not make it a separate question (otherwise you'd get invalid combos like longform + 20%). If the user wants to deviate from the default, they can use a free-text sentence to override ("I want longform + 60%"), see "How to Deviate from the Default Ratio" below
2	Theme	tufte / press / other registered themes (read theme-profiles/index.json)	AI recommends one with a one-line rationale
3	Layout width	narrow / regular / wide / full	AI recommends one; default is regular
4	Illustration mode (required; "default pass" is not allowed)	none / user-assets / placeholders / ai-generated	One sentence: "This only determines whether to use an external Image component; Raw is unaffected"
5	Cover (3:4 book-cover-style title graphic, above TOC and main content)	On (default) / Off	AI recommends "On" with a one-line composition idea (what kind of main visual + which cover template A/B/C/D/E). For briefing / dialogue, may recommend "Off". See details in references/cover.md

TOC defaults to On: Since it has only one toggle + almost all articles should have it, you may briefly mention it in the opening message of the Plan Checkpoint as "TOC is on by default; tell me if you want it off", no need to make it a standalone question.

Items already at default and do not need separate confirmation (but must still be mentioned in the opening message as "If you need to change, let me know", giving the user a chance to override; they must not be completely hidden):

• Final article language: Follows source language (unless already specified or translated earlier).
• Whether editing, cutting, restructuring, or rewriting tone is allowed: Allowed by default (within the information retention ratio specified above).
• Whether a first screen sample is shown: Yes, by default (that is Phase 4).
• TOC: On by default.

If the user says "You decide" for the theme → Take your first recommendation, but still include it alongside other candidates in the options, marked as "Default · AI Recommended", leaving room for reconsideration; do not skip the theme question.

How to deviate from the default information retention ratio: Each article type has a built-in recommended retention ratio (see table above). In the vast majority of cases, the default is sufficient. If the user wants fine-tuning (e.g., "longform but only 60%" → a heavily edited long-form article), let the user write a sentence in the free text after the opening explanation, e.g., "I want + <X%>" to override. After receiving the override, the AI must record in plan/plan.md's Brief section both the "type / default retention / user override to X%" and remind the user that this is a "non-default combination" — such combos require the Main Agent to manually adjust text/visual proportions when writing each section.

Plan Checkpoint opening message template (send a brief explanation before collecting decisions):

plan/plan.md has been written (passed self-check). I'll confirm 5 things with you one by one: article type / theme / layout width / illustration mode / cover.

My recommendations for your reference (I won't make the choice for you):
- Type: <X> (includes default info retention <Y%>. Rationale: …)
- Theme: <theme> (Rationale: …)
- Layout width: <width> (Rationale: …)
- Illustration mode: <strategy> (Rationale: …)
- Cover: On / Off (Rationale: …; if On, composition idea: …)

Items defaulting but you can override: language follows source language; editing/cutting/restructuring allowed; TOC on; first screen sample will be created next.
If you want to deviate from the default info retention ratio for the type, tell me the specific percentage after answering below (e.g., "longform but only 60%").

Let's go through each item now.

After sending the above explanation, immediately use AskQuestion to submit 5 questions (or list 5 questions with numbers and wait for replies if no tool is available). All 5 items must be answered before proceeding to Phase 4; if the user provides a "non-default retention ratio" in free text, first confirm that it has been recorded in plan/plan.md before proceeding to Phase 4.

---

Phase 4 — First Spread (The "Chapter 1 Approval" of the Article)

Create "Cover (if on) + First Screen + First Section + One Representative Visual Block". The scaffold creates the workspace here:

# Default: cover on
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=<id>
# If user chose "Cover: Off" at 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 (installs the latest published reacticle from npm) + source/ plan/ review/ memory directories + an assembler article/Article.tsx + one example section component (+ a default article/Cover.tsx, unless --no-cover). See references/scaffold.md for details.

Write the first screen (Hero / Lead) into the assembler article/Article.tsx; the first Section MUST be a standalone component file article/sections/01-*.tsx (this is the code anchor for subsequent parallel work, see references/section-build.md). Cover (if on): Replace the <CoverPlaceholder /> in article/Cover.tsx with a custom graphic composition based on the theme and article theme, keeping the outer shell (3:4 container + print page break) unchanged. Cover design guidelines are in references/cover.md. npm run dev to preview. This determines title tone / font size / content density / Raw style / illustration approach / theme suitability.

After completing the first section, follow the mandatory quality inspection protocol: create a First Spread Reviewer SubAgent, write review/first-spread-review.md (including the 5-item cover self-check, see references/cover.md), and then fix any issues before proceeding to Checkpoint 2.

---

Checkpoint 2 · First Spread (★ Hard Node: MUST STOP)

Have the user approve the first screen + first section, and select the subsequent development mode. The same decision collection rules from Checkpoint 1 apply: two items confirmed independently; no packaging; prefer AskQuestion; if no tool, list with numbers and wait for replies.

First send a brief message:

The first screen + first section are done. Preview at localhost via npm run dev.
See review/first-spread-review.md for the inspection result (fixes applied; list of what was fixed).
Please independently confirm two things: 1) Acceptance result 2) Subsequent development mode.

Then use AskQuestion to submit two independent questions (or list two questions with numbers and wait for replies):

1. Acceptance Result — Options: Approved · Proceed to full generation / Minor revisions – I will specify what to change / Theme or layout unsuitable – Return to Checkpoint 1.
2. Subsequent Development Mode — Options: A · Single-Agent Sequential (default · most stable · most consistent style) / B · Multi-Agent Parallel (fastest · slight style variation).

Do NOT package these two into a single "Approved + A, OK?" question — the user might want "Approved but B" or vice versa. Proceed to Phase 5 only after receiving answers to both questions.

---

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.

Hard rule: Each Section MUST be a standalone component file (article/sections/NN-*.tsx), it is STRICTLY FORBIDDEN to write multiple Sections directly into a single component. article/Article.tsx is only an assembler: it imports and orders Sections, and is owned by the Main Agent. Large Raw blocks also go into separate article/raw-blocks/NN-*.tsx files. File-level isolation is the prerequisite for multi-agent parallelism.

Development modes (selected at Checkpoint 2):

• A · Single-Agent Sequential (default): The Main Agent writes each sections/NN-*.tsx in order; the most stable, most consistent style.
• B · Multi-Agent Parallel: Each subagent owns one sections/NN-*.tsx file and works on it in parallel; the Main Agent is responsible for merging and stability — maintains import order in Article.tsx, runs npm run typecheck / build, ensures theme and style consistency, resolves conflicts. Subagent prompt template in references/section-build.md.

Other principles: Text is the main body; all Raw uses --ra-* theme tokens; no wild styles; 100% information retention is primarily achieved through a long-form structure with Raw/illustrations as enhancements; low information density allows for a higher proportion of visual blocks, but the result must still be an article format.

After completing each section, must follow the mandatory quality inspection protocol with a Section Reviewer SubAgent: Does it complete the outline task? Does it meet the information retention ratio? Does it connect with the previous/next sections? Is it over-componentized? Is there enough body text? Do Raw and illustrations have a clear purpose? Is the section number self-consistent?

The SubAgent returns pass/fail + fix points as a message (pass: one line "OK"; fail: list fix points), do NOT write a review/section-NN-review.md file. Upon receiving fail items, the Main Agent directly fixes the corresponding section file and then reports delivery of this section.

---

Phase 6 — Final Review (Three-Perspective Review)

Review from the reader's, theme's, and technical perspectives; produce review/final-review.md + a fix list. Full mandatory checklist in references/review-checklist.md. Three Reviewers are recommended (at least one independent SubAgent if Teams are not available):

1. Editorial Reviewer: Article-ness, information inclusion/exclusion, structure.
2. Visual Reviewer: Theme, Raw, illustrations, mobile responsiveness.
3. Technical Reviewer: Build, console, code/formulas, accessibility.

Core red lines: It must still be an article (not an application) · Information retention ratio matches the Plan · Must-retain information is present · Theme tone is consistent · Raw has no wild styles · No overt AI flavor · Readable on desktop + mobile · HTML is buildable, openable, and shareable.

---

Phase 7 — Repair (Minimal Chunks)

Repair in minimal units; rules in references/repair-policy.md. Forbidden: rewriting the entire article over one fix point / modifying confirmed article structure to fix visuals / deleting user-specified required information to compress content. Only write review/repair-log.md if repairs were made (no repairs / one-pass: do not write).

---

Checkpoint 3 · Final (★ Delivery Confirmation)

After final review fixes, STOP and let the user independently confirm the delivery decision (do not skip with "I'll just export HTML; OK if that's fine" or proceeding directly to default). Prefer AskQuestion; if no tool, list questions with numbers in a message and wait for replies.

• Delivery Decision — Options: Approved · Export HTML for delivery / Approved · Export both HTML and PDF / Still needs local fixes – I will specify what to fix / Pause for now – I want to take another look.

Only one decision here, but still actively stop and ask; do not silently proceed with the default HTML export.

---

Phase 8 — Delivery

Build and deliver (commands in references/html-output.md):

• article/article.html (self-contained single page, CSS + JS inlined, can be opened offline) — Primary deliverable.
• Optional article/article.pdf: Only generated if the user chose "Approved · Export both HTML and PDF" at Checkpoint 3. Command:

  bash <path-to-beautiful-article>/scripts/html-to-pdf.sh
  

  The script detects system…

[truncated for translation]