What Is the beautiful-article Skill? Purpose and Workflow Explained

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, 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, the process flows as follows:

1. Phase 0 – Intake: Ingest the raw source material.
2. Phase 1 – Source → Markdown: Convert input to source.md.
3. Phase 2 – Editorial Planning: Generate 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 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. 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:

# 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:

npm run build   # Outputs article/article.html

For PDF generation, execute the conversion helper:

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: Main skill descriptor defining capabilities and entry points.
• skills/beautiful-article/manifest.json: Release metadata and version information.
• skills/beautiful-article/README.md: High-level workflow documentation.
• skills/beautiful-article/scripts/scaffold.sh: Bootstraps a Vite + React + TypeScript workspace.
• skills/beautiful-article/scripts/html-to-pdf.sh: Converts final HTML to PDF format.
• 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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}