How Theme Profiles Are Defined for the beautiful-article Skill: A Complete Guide

Theme profiles in the beautiful-article skill are defined through a two-part system consisting of a metadata catalogue in index.json and human-readable markdown guidance files, enabling AI agents to select and apply appropriate visual styles during article scaffolding.

The beautiful-article skill in the ConardLi/garden-skills repository uses a declarative theme-profile architecture to bridge authoring guidance with runtime visual implementation. This system allows AI agents to intelligently match article content with appropriate visual styles based on mood, use-case constraints, and technical requirements. Understanding how theme profiles are defined for the beautiful-article skill is essential for customizing the scaffolding process or extending the skill with new visual themes.

The Two-Part Theme Profile Architecture

Theme profiles are defined in two distinct layers: a machine-readable metadata catalogue and detailed human-readable guidance documents.

The Metadata Catalogue (index.json)

The master registry for all available themes resides in skills/beautiful-article/theme-profiles/index.json. This JSON file serves as the canonical source for theme discovery and validation.

Each entry in the catalogue defines:

• id: The unique identifier used for CLI arguments and theme selection
• runtimeTheme: The corresponding runtime theme name consumed by React components
• label: A human-readable display name for UI presentation
• mood: Descriptive keywords capturing the aesthetic intent
• bestFor: An array of content types where the theme excels (e.g., ["longform", "full-report", "explainer"])
• notFor: Constraints and anti-patterns where the theme performs poorly
• profile: The filename of the markdown guidance document (e.g., tufte.md)
• canonicalRuntimeMd: Path to the runtime theme definition in the component library

Example entry for the tufte theme:

{
  "id": "tufte",
  "runtimeTheme": "tufte",
  "label": "Tufte · Data-Ink",
  "mood": "证据、数据、克制、低装饰；让读者凑近去读",
  "bestFor": ["longform", "full-report", "explainer", "review", "tutorial"],
  "notFor": ["十米外观看的演示幻灯片", "移动端优先且需要大量边注的场景"],
  "profile": "tufte.md",
  "canonicalRuntimeMd": "src/theme/themes/tufte/tufte.md"
}

The Human-Readable Profile Files (.md)

Each theme includes a dedicated markdown file in the same directory (e.g., tufte.md, press.md, shannon.md) containing authoring guidance for the AI planner. These files describe how to structure content to maximize the theme's visual strengths.

The header of each profile file declares the runtime theme ID that gets injected into the React component hierarchy:

> 运行时主题持有（`data-theme="tufte"`）。本文件是"如何选择和使用这个主题"。
- **runtime theme id**：`tufte`（`<ThemeProvider theme="tufte">`）

According to the source code in skills/beautiful-article/theme-profiles/tufte.md, these files instruct the AI on typography constraints, layout preferences, and content organization strategies specific to that visual style.

The Scaffolding Workflow

During article creation, skills/beautiful-article/scripts/scaffold.sh orchestrates theme profile selection and application. The script performs four critical operations:

1. Validation: Reads index.json to verify that the --theme=<id> argument matches a valid entry in the catalogue
2. Profile Copying: Copies the selected theme's markdown guidance into the new article workspace
3. State Persistence: Writes the chosen theme ID to a hidden .theme file for later reference
4. Runtime Injection: Embeds the theme identifier into the generated React entry point

At line 111 of scaffold.sh, the script handles the integration logic that wires the runtime theme into the component hierarchy.

Runtime Theme Integration

The selected theme profile transitions from configuration to execution through React's Context API. The generated article/main.tsx file imports ThemeProvider from src/theme/ThemeProvider.tsx and initializes the theme according to the runtimeTheme value defined in index.json:

<ThemeProvider theme="press">
  {/* …article content… */}
</ThemeProvider>

The ThemeProvider component registers runtime theme IDs and applies corresponding CSS variables, typography scales, and layout constraints defined in the component library's theme definitions (referenced by canonicalRuntimeMd paths).

CLI Usage Examples

List all available theme profiles defined in the catalogue:

bash scripts/scaffold.sh --list-themes

Create a new article using the "press" theme profile:

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

The AI planner consumes the profile during content generation by reading the markdown guidance:

// Pseudo-code used by the skill's planner
const profile = await readFile(`theme-profiles/${themeId}.md`);
const guidance = extractGuidance(profile);

Summary

• Theme profiles are defined in skills/beautiful-article/theme-profiles/index.json as a metadata catalogue containing IDs, runtime mappings, use-case constraints, and file references.
• Each profile includes a human-readable markdown file (e.g., tufte.md) providing AI authoring guidance and runtime theme IDs.
• The scaffold.sh script validates theme selections against index.json, copies guidance files, and persists theme state to a .theme file.
• Runtime themes are applied via ThemeProvider in generated article/main.tsx files, linking authoring guidance to visual implementation.
• The architecture creates a declarative contract between content planning and runtime rendering in the ConardLi/garden-skills repository.

Frequently Asked Questions

How does the scaffolding script validate theme profile selections?

The script reads skills/beautiful-article/theme-profiles/index.json and checks the id field of each entry against the --theme CLI argument. If the provided ID does not exist in the catalogue, the script exits with an error before creating any files, ensuring only defined theme profiles can be used.

What is the relationship between the profile markdown and the runtime theme?

The markdown files contain authoring guidance for the AI planner, while the runtimeTheme field in index.json maps to the actual React theme implementation. The canonicalRuntimeMd property references the technical theme definition, and the profile property references the human-readable guidance—together they ensure visual consistency between AI-generated content and rendered output.

Where is the selected theme stored during article development?

After scaffolding, the theme ID is written to a hidden .theme file in the article workspace. This file allows subsequent scripts and the development server to reference the active theme without reparsing CLI arguments, maintaining state between build steps.

Can I add a custom theme profile to the beautiful-article skill?

Yes. Create a new entry in skills/beautiful-article/theme-profiles/index.json with a unique id and runtimeTheme, add a corresponding .md guidance file in the same directory, and ensure your component library includes a matching implementation in src/theme/themes/{your-theme}/. The scaffold.sh script will automatically recognize the new profile when reading the catalogue.

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