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

> Discover how theme profiles define beautiful-article skill styles. Learn about the metadata catalogue and markdown guidance for AI agent article scaffolding.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Theme profiles in the beautiful-article skill are defined through a two-part system consisting of a metadata catalogue in [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/tufte.md))
- **canonicalRuntimeMd**: Path to the runtime theme definition in the component library

Example entry for the tufte theme:

```json
{
  "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`](https://github.com/ConardLi/garden-skills/blob/main/tufte.md), [`press.md`](https://github.com/ConardLi/garden-skills/blob/main/press.md), [`shannon.md`](https://github.com/ConardLi/garden-skills/blob/main/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:

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

```

According to the source code in [`skills/beautiful-article/theme-profiles/tufte.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh) orchestrates theme profile selection and application. The script performs four critical operations:

1. **Validation**: Reads [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/article/main.tsx) file imports `ThemeProvider` from [`src/theme/ThemeProvider.tsx`](https://github.com/ConardLi/garden-skills/blob/main/src/theme/ThemeProvider.tsx) and initializes the theme according to the `runtimeTheme` value defined in [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/index.json):

```tsx
<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
bash scripts/scaffold.sh --list-themes

```

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

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

```

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

```typescript
// 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/tufte.md)) providing AI authoring guidance and runtime theme IDs.
- The [`scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scaffold.sh) script validates theme selections against [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/index.json), copies guidance files, and persists theme state to a `.theme` file.
- Runtime themes are applied via `ThemeProvider` in generated [`article/main.tsx`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/scaffold.sh) script will automatically recognize the new profile when reading the catalogue.