# What Is the beautiful-article Skill? Purpose and Workflow Explained > Discover the purpose of the beautiful-article skill. Transform raw content like URLs and PDFs into polished HTML articles with optional PDF output using a structured workflow. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: deep-dive - Published: 2026-09-02 --- **The beautiful-article skill is an editorial harness that converts raw source materials—URLs, PDFs, DOCX files, Markdown, or plain text—into polished, self-contained HTML articles with optional PDF output, ensuring consistent typography and visual design through a structured multi-phase workflow.** Located in the `ConardLi/garden-skills` repository, the **beautiful-article** skill provides AI agents with a methodology for producing high-quality, aesthetically consistent long-form articles. Unlike generic web-app generators, this skill focuses specifically on read-ready, share-ready editorial content with strict thematic consistency and three hard checkpoints to ensure quality control. ## Core Architecture: Skill Layer vs. Runtime Layer The architecture separates editorial orchestration from component rendering. According to the source code in [`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md), the system operates across two distinct layers: - **beautiful-article** (the skill itself): Handles planning, writing, reviewing, and delivery. It provides the methodology, checkpoints, theme picker, and sub-agent reviewers. - **reacticle** (the runtime component protocol): Supplies the component vocabulary—including `Article`, `Hero`, `Section`, `Quote`, and `Raw`—and manages the 11 authoring themes that the skill compiles into final output. This separation ensures that the skill manages editorial decisions while `reacticle` handles the technical implementation of layout and styling. ## The 10-Phase Editorial Workflow The skill enforces a rigorous workflow with numbered phases and hard checkpoints to maintain quality control. As defined in [`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md), the process flows as follows: 1. **Phase 0 – Intake**: Ingest the raw source material. 2. **Phase 1 – Source → Markdown**: Convert input to [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/source.md). 3. **Phase 2 – Editorial Planning**: Generate [`plan.md`](https://github.com/ConardLi/garden-skills/blob/main/plan.md) defining article type, theme, and assets. 4. **Checkpoint 1 – Plan**: Confirm five independent decisions—article type, theme, width, image mode, and cover. 5. **Phase 4 – First Spread**: Create cover, hero, and first section. 6. **Checkpoint 2 – First Spread**: Review and optionally A/B-test the initial layout. 7. **Phase 5 – Full Article Build**: Assemble all sections using `reacticle` components. 8. **Phase 6 – Final Review**: Conduct editorial, visual, and technical reviews. 9. **Checkpoint 3 – Delivery**: Decide between HTML-only or HTML + PDF output. 10. **Phase 8 – Delivery**: Output [`article.html`](https://github.com/ConardLi/garden-skills/blob/main/article.html) and optionally `article.pdf`. ## Theme-Driven Design and the Raw Escape Hatch Every article is built from a registered **theme profile** (such as *tufte*, *press*, or *bayer*) defined in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json). Each theme establishes a Markdown contract and a CSS token bundle that guarantees visual consistency across all rendered components. The **`Raw`** component provides an escape hatch for free-form content blocks while maintaining token-based styling. This ensures that switching themes automatically rewires all raw content to match the new design system without manual refactoring. ## Scaffolding and Building Articles To initialize a new article workspace, use the scaffold script located at [`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh): ```bash # Scaffold with default cover and tufte theme bash ./skills/beautiful-article/scripts/scaffold.sh ./my-article --theme=tufte # Scaffold without cover using press theme bash ./skills/beautiful-article/scripts/scaffold.sh ./brief --theme=press --no-cover # List available themes bash ./skills/beautiful-article/scripts/scaffold.sh --list-themes ``` After content generation, build the single-file HTML with inlined CSS and JavaScript: ```bash npm run build # Outputs article/article.html ``` For PDF generation, execute the conversion helper: ```bash bash ./skills/beautiful-article/scripts/html-to-pdf.sh ``` ## Key Files in the Repository The skill's functionality is distributed across several critical files: - **[`skills/beautiful-article/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/SKILL.md)**: Main skill descriptor defining capabilities and entry points. - **[`skills/beautiful-article/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/manifest.json)**: Release metadata and version information. - **[`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md)**: High-level workflow documentation. - **[`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh)**: Bootstraps a Vite + React + TypeScript workspace. - **[`skills/beautiful-article/scripts/html-to-pdf.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/html-to-pdf.sh)**: Converts final HTML to PDF format. - **[`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json)**: Registry of the 11 authoring themes. - **`skills/beautiful-article/assets/scaffold-template/`**: Template files for new article workspaces. ## Summary - The **beautiful-article** skill transforms arbitrary source inputs into publication-ready HTML articles through a structured 10-phase workflow. - **Three hard checkpoints** ensure editorial control at planning, initial layout, and delivery stages. - **Theme-driven architecture** via `reacticle` provides 11 distinct design profiles with automatic CSS token application. - **Dual-layer separation** distinguishes editorial orchestration (the skill) from component rendering (reacticle runtime). - Source code resides in `ConardLi/garden-skills` with primary documentation in [`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md). ## Frequently Asked Questions ### What input formats does the beautiful-article skill support? The skill accepts raw source materials including URLs, PDFs, DOCX files, Markdown documents, and plain-text notes. During **Phase 1**, all inputs are normalized to [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/source.md) to ensure consistent processing through the editorial pipeline. ### How does the checkpoint system ensure editorial quality? The three hard checkpoints (**Checkpoint 1 – Plan**, **Checkpoint 2 – First Spread**, and **Checkpoint 3 – Delivery**) require explicit confirmation before proceeding. **Checkpoint 1** specifically enforces five independent decisions regarding article type, theme, width, image mode, and cover presence, preventing AI agents from proceeding with ambiguous specifications. ### What is the relationship between beautiful-article and reacticle? **beautiful-article** is the editorial skill that manages workflow, planning, and review, while **reacticle** is the runtime component protocol that supplies the actual UI vocabulary (such as `Hero`, `Section`, and `Quote` components) and the 11 authoring themes. The skill orchestrates content; reacticle renders it. ### Can I use custom themes with the beautiful-article skill? Yes. Themes are registered in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json). Each theme defines a Markdown contract and CSS token bundle. You can scaffold with any registered theme using the `--theme` flag, and the `Raw` component ensures that free-form content adheres to the selected theme's token system even when custom HTML is required.