How Authoring Theme Profiles Work in the beautiful-article Skill: Visual Design Meets AI Guidance

Authoring theme profiles in the beautiful-article skill separate runtime CSS from AI authoring guidance, using structured markdown files to define aesthetic intent while JSON indexing maps content types to appropriate themes.

The beautiful-article skill in the ConardLi/garden-skills repository implements a sophisticated theming architecture that decouples visual rendering from editorial planning. This system allows AI agents to select appropriate design constraints based on article content type, ensuring that the final rendered output matches the intended tone and structure.

What Are Authoring Theme Profiles?

Authoring theme profiles serve as editorial blueprints that guide AI agents during article planning, distinct from the runtime stylesheets that control visual presentation. Each profile stored in skills/beautiful-article/theme-profiles/<id>.md defines the aesthetic intent, suitable article types, Raw component styling preferences, media guidelines, and density-dependent suggestions for a specific visual theme.

The system maintains a strict separation between authoring guidance (what the AI reads while planning) and runtime styling (the CSS applied during rendering). According to the source code, the authoring profile describes the "aesthetic intent, suitable article types, Raw style, media guidelines, code/formula styling, and density-dependent suggestions" that an AI should follow when structuring content.

Profile Storage and Indexing

The profile collection is organized through a central registry at skills/beautiful-article/theme-profiles/index.json. This JSON index serves as the master directory, mapping each profile id to its corresponding runtime theme used by the component library in src/theme/themes/<id>/.

The index.json structure contains critical metadata fields that the AI evaluates during selection:

• bestFor: Array of content types ideally suited to this theme (e.g., essay, tutorial, report)
• mood: Descriptive tags indicating the emotional or tonal characteristics
• notFor: Content types that should avoid this theme
• runtimeTheme: The identifier linking the authoring profile to its visual implementation

// Example structure from theme-profiles/index.json
{
  "id": "tufte",
  "label": "Tufte Style",
  "bestFor": ["longform", "full-report", "explainer"],
  "runtimeTheme": "tufte"
}

Individual profiles like theme-profiles/tufte.md contain detailed markdown documentation specifying typography rules, component preferences, and content density recommendations that guide the AI's structural decisions.

The Theme Selection Workflow

The selection process follows a four-stage pipeline defined in skills/beautiful-article/references/theme-selection.md:

1. Read the Index

The AI first parses theme-profiles/index.json to obtain the complete catalog of available themes, extracting bestFor, mood, and notFor tags for each candidate.

2. Match Source Material

Based on the source document's content type, tone, or explicit requirements, the AI selects one to two candidate themes. For example, technical documentation maps to the tufte theme, while narrative journalism aligns with the press theme.

3. Load Detailed Guidance

The AI reads the full profile markdown file (theme-profiles/<id>.md) for the selected candidates, accessing specific constraints regarding typography, Raw component usage, and media styling.

4. Record the Decision

Finally, the AI writes the chosen theme identifier and selection rationale into plan/plan.md under the Theme section, following the structure defined in skills/beautiful-article/references/plan-template.md.

<!-- Excerpt from plan.md output -->

## Theme

**Selected:** tufte  
**Rationale:** Technical tutorial requiring dense marginalia and 
formal typography consistent with academic publishing standards.

Runtime Coupling and Validation

A critical architectural constraint ensures consistency between planning and rendering: the authoring profile's runtimeTheme field must match an existing runtime theme registered in ThemeProvider.tsx. If a profile exists without a corresponding runtime theme implementation, the theme remains a candidate only and cannot be used for final article generation.

This coupling prevents the AI from selecting aesthetic guidelines that lack visual implementations. The runtime themes (tufte, press, etc.) perform the actual visual rendering, while the authoring profiles ensure the AI structures content appropriately for those visual constraints.

Scaffolding Support with CLI Validation

The skills/beautiful-article/scripts/scaffold.sh script enforces theme validity during workspace creation. When creating a new article, the script validates that the --theme argument corresponds to an id present in theme-profiles/index.json, then copies the selected profile into the workspace for reference during development.

# List available theme ids

bash skills/beautiful-article/scripts/scaffold.sh --list-themes

# Scaffold a new article using the "press" theme

bash skills/beautiful-article/scripts/scaffold.sh ./my-article --theme=press

The script prevents invalid theme selection at the scaffolding stage, ensuring that only indexed themes with complete authoring profiles can initialize new article workspaces.

Practical Implementation Examples

When building external tooling or extensions for the beautiful-article skill, you can programmatically access the theme index:

// Example: reading the index in a Node script (used by the skill’s planner)
import fs from 'fs';

const index = JSON.parse(
  fs.readFileSync('skills/beautiful-article/theme-profiles/index.json', 'utf-8')
);

const candidate = index.find(t => t.bestFor.includes('essay'));
console.log(`Pick theme ${candidate.id} (${candidate.label})`);

Theme profiles utilize structured markdown sections to define constraints:

<!-- Excerpt from theme-profiles/tufte.md -->

## 适合 / 不适合的文章类型

- **适合**：`longform`、`full-report`、`explainer`、`review`、`tutorial`
- **不适合**：需要 10 米外观看的幻灯片…

Summary

• Authoring theme profiles are markdown-based editorial guidelines stored in theme-profiles/<id>.md that direct AI content planning.
• The index.json registry maps profiles to runtime themes and tags them with bestFor/notFor content classifications.
• Selection workflow involves reading the index, matching content types, loading detailed profiles, and recording decisions in plan/plan.md.
• Runtime coupling requires every authoring profile to reference a valid runtimeTheme implemented in the component library's ThemeProvider.tsx.
• Scaffolding validation ensures only registered themes can initialize workspaces through scripts/scaffold.sh.

Frequently Asked Questions

What is the difference between an authoring profile and a runtime theme?

An authoring profile is a markdown file read by AI agents during article planning that defines editorial constraints, suitable content types, and stylistic intent. A runtime theme is the actual CSS and component configuration in src/theme/themes/<id>/ that renders the final visual output. The profile guides what to write; the runtime theme determines how it looks.

How does the AI choose between multiple suitable themes?

The AI evaluates the bestFor, mood, and notFor tags in theme-profiles/index.json to identify 1-2 candidate themes matching the source material's content type and tone. It then reads the detailed markdown profiles for these candidates to assess which specific aesthetic guidelines best fit the article's structural requirements before recording the final decision.

What happens if I specify a theme that exists only as a profile but has no runtime implementation?

According to the source code in references/theme-selection.md, if a profile's runtimeTheme field references a non-existent implementation, that theme is treated as a candidate only and cannot be used for final generation. The scaffold.sh script prevents this by validating against the index, but manual workspace creation should verify that the chosen profile has a corresponding runtime theme registered in ThemeProvider.tsx.

Can I create custom theme profiles for specialized content types?

Yes, custom profiles can be added by creating new markdown files in theme-profiles/ and registering them in theme-profiles/index.json with appropriate bestFor tags and a valid runtimeTheme mapping. The profile should define specific aesthetic intent and content constraints, and the scaffolding script will automatically recognize any theme ID present in the index.

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