How Themes Are Selected in the web-video-presentation Skill: A Technical Deep Dive

The web-video-presentation skill selects themes by validating the user-provided theme parameter against the catalogue in skills/beautiful-article/theme-profiles/index.json, automatically falling back to a random theme when no preference is specified.

The web-video-presentation skill in the ConardLi/garden-skills repository generates visually consistent video presentations by integrating with the Beautiful Article theme engine. Understanding how this skill resolves visual styling requires examining the theme catalogue structure, the selection algorithm, and the runtime injection mechanism that applies design tokens to the final output.

Theme Catalogue Architecture

The skill relies on a centralized JSON manifest to discover available visual styles. This catalogue-based approach decouples theme definitions from the selection logic, enabling modular additions of new design profiles without modifying core skill code.

Index.json Structure

All valid theme identifiers are registered in skills/beautiful-article/theme-profiles/index.json. This manifest maps theme keys to corresponding markdown definition files:

• Theme keys: String identifiers such as vignelli, tufte, or knuth
• Value mapping: Each key points to a relative path for the theme's markdown specification containing palette definitions, typography scales, and layout constraints
• Location: skills/beautiful-article/theme-profiles/index.json serves as the single source of truth for theme availability

Markdown Theme Definitions

Individual themes are stored as markdown files within the same directory (e.g., vignelli.md, tufte.md, knuth.md). These files contain the actual design system parameters—color hex codes, font stack declarations, spacing units, and component-specific styling rules—that the skill injects into the generated presentation markup.

Theme Selection Algorithm

The selection logic resides in the skill's entry point at skills/web-video-presentation/skill.ts (or the equivalent JavaScript implementation). The algorithm follows a deterministic priority order:

1. Parameter Validation

When the skill executes, it first inspects the incoming parameters for a theme property. If params.theme exists and matches a key present in the theme index, the skill immediately selects that theme:

import themeIndex from '../../skills/beautiful-article/theme-profiles/index.json';

const themeKeys = Object.keys(themeIndex);
const selectedTheme = params.theme && themeKeys.includes(params.theme)
    ? params.theme
    : getRandomTheme(themeKeys);

2. Random Fallback Mechanism

If the theme parameter is omitted or contains an invalid identifier, the skill executes a pseudorandom selection from the available catalogue keys:

function getRandomTheme(keys: string[]): string {
    const randomIndex = Math.floor(Math.random() * keys.length);
    return keys[randomIndex];
}

This ensures every presentation renders with a valid design system even when users do not specify a visual preference.

Theme Application Process

After resolving the theme name, the skill performs two additional operations to apply the visual layer:

Loading Theme Definitions

The skill constructs the file path to the selected theme's markdown definition using string interpolation:

import { readFileSync } from 'fs';

function loadThemeDefinition(themeName: string): string {
    const themePath = `../../skills/beautiful-article/theme-profiles/${themeName}.md`;
    return readFileSync(themePath, 'utf-8');
}

Style Injection

The raw markdown content containing CSS variables and component styles is injected into the HTML/React component tree that renders the video presentation. This occurs in the skill's rendering pipeline, ensuring the videoUrl asset displays within the context of the selected visual language (Swiss minimalism for vignelli, academic typography for tufte, etc.).

Practical Usage Examples

Explicit Theme Selection

Force a specific visual style by providing the theme identifier in the skill parameters:

{
  "skill": "web-video-presentation",
  "params": {
    "theme": "tufte",
    "videoUrl": "https://example.com/lecture.mp4"
  }
}

Random Theme Selection

Omit the theme parameter to trigger the random selection behavior:

{
  "skill": "web-video-presentation",
  "params": {
    "videoUrl": "https://example.com/intro.mp4"
  }
}

Summary

• Theme registration: All valid themes are catalogued in skills/beautiful-article/theme-profiles/index.json, mapping identifiers to markdown definition files.
• Selection priority: The skill checks params.theme first; if missing or invalid, it selects randomly from available keys using Math.random() and Object.keys().
• File resolution: Selected themes load from skills/beautiful-article/theme-profiles/${themeName}.md using filesystem reads.
• Visual application: Theme markdown is injected into the presentation markup, styling the video container according to the chosen design system (Vignelli, Tufte, or Knuth).

Frequently Asked Questions

How do I specify a theme when calling the web-video-presentation skill?

Pass the theme parameter with a valid string identifier (e.g., "vignelli", "tufte", or "knuth") in the skill's JSON payload. The skill validates this against the keys defined in skills/beautiful-article/theme-profiles/index.json before resolving the corresponding markdown file.

What happens if I don't provide a theme parameter?

When the theme parameter is omitted or contains an unrecognized value, the skill automatically executes a random selection algorithm. It generates a random index based on Object.keys(themeIndex).length and selects the corresponding theme from the catalogue, ensuring the presentation always renders with a valid design system.

Where are the actual theme styles defined?

Theme-specific styling—including color palettes, typography scales, and layout constraints—is defined in markdown files located at skills/beautiful-article/theme-profiles/. Each theme has its own .md file (such as vignelli.md or tufte.md) that the skill reads and injects into the final HTML output during the rendering phase.

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