Key Files and References for the Web-Video-Presentation Skill in Garden

The web-video-presentation skill provides a complete Vite + React + TypeScript scaffold for converting scripts into cinematic 16:9 web presentations, with core logic residing in skills/web-video-presentation/ and guided by six canonical reference documents.

The web-video-presentation skill inside the ConardLi/garden-skills repository enables agents to generate click-driven presentations suitable for screen recording. It combines a chapter-step cursor model, hard collaboration checkpoints, and a token-based theme architecture. Understanding the file structure is essential for customizing the scaffold, managing the audio pipeline, or extending the theme system.

Core Architecture Files

Project Metadata and Documentation

Every skill in the garden starts with its identity documents. The web-video-presentation skill defines its package metadata in skills/web-video-presentation/manifest.json, which specifies the name, description, and homepage. Human-readable specifications and workflow summaries live in skills/web-video-presentation/SKILL.md, while end-user quick-start guides and demo screenshots are located in skills/web-video-presentation/README.md.

Scaffolding and Build Configuration

The entry point for project generation is skills/web-video-presentation/scripts/scaffold.sh. This bash script performs one-click project initialization and handles theme selection via the --theme flag. Once generated, the project relies on skills/web-video-presentation/templates/vite.config.ts for build tooling configuration, ensuring the Vite bundler correctly processes the React and TypeScript assets.

React Components and UI Layer

The runtime UI is assembled from several key components within the templates directory. The application bootstrap occurs in skills/web-video-presentation/templates/src/main.tsx, which mounts the React tree. The shell component in skills/web-video-presentation/templates/src/App.tsx maintains the chapter registry and high-level layout.

Visual rendering happens inside skills/web-video-presentation/templates/src/components/Stage.tsx, which creates the full-screen 16:9 canvas (1920×1080) that scales responsively while maintaining aspect ratio. Navigation feedback is provided by skills/web-video-presentation/templates/src/components/ProgressBar.tsx, a hidden UI element that only appears on cursor hover to keep recordings clean.

State Management and Custom Hooks

Presentation state is managed through a collection of custom hooks in the templates directory:

• useStepper (skills/web-video-presentation/templates/src/hooks/useStepper.ts): Implements the global step counter with persistent storage, tracking the current position across the chapter-step cursor model.
• useStageScale (skills/web-video-presentation/templates/src/hooks/useStageScale.ts): Maintains the fixed 1920×1080 stage dimensions while scaling the output to fit the browser viewport.
• useAutoMode (skills/web-video-presentation/templates/src/hooks/useAutoMode.ts): Provides optional auto-play functionality essential for hands-free recording workflows.
• useAudioPlayer (skills/web-video-presentation/templates/src/hooks/useAudioPlayer.ts): Handles playback of synthesized narration audio synchronized to presentation steps.

Audio Pipeline and TTS Integration

The skill includes a complete text-to-speech workflow. Narration extraction is handled by skills/web-video-presentation/templates/scripts/extract-narrations.ts, which scans all narrations.ts files throughout the project and aggregates them into audio-segments.json.

Audio synthesis is orchestrated by skills/web-video-presentation/templates/scripts/synthesize-audio.sh, which loops over segments and delegates to TTS providers. Built-in provider implementations include skills/web-video-presentation/templates/scripts/tts-providers/minimax.sh and skills/web-video-presentation/templates/scripts/tts-providers/openai.sh. Extensibility instructions are documented in skills/web-video-presentation/templates/scripts/tts-providers/README.md.

Theme System and Tokens

Visual styling follows a token-based architecture. Each theme resides in its own subdirectory under skills/web-video-presentation/themes/, containing two critical files:

• tokens.css: Defines the design system variables including colors, fonts, and spacing (e.g., skills/web-video-presentation/themes/paper-press/tokens.css).
• theme.json: Provides human-readable metadata describing the theme's mood and intended use case (e.g., skills/web-video-presentation/themes/paper-press/theme.json).

Reference Documentation

The skill enforces a four-phase workflow through six canonical reference documents stored in skills/web-video-presentation/references/:

Document	Purpose	Phase
CHAPTER-CRAFT.md	Implementation guide for building individual chapters	Phase 2.4
SCRIPT-STYLE.md	Converting source articles into script.md format	Phase 1.2
OUTLINE-FORMAT.md	Creating structured outline.md documents	Phase 1.2
THEMES.md	Theme selection criteria and creation guidelines	Checkpoint Plan
AUDIO.md	Audio synthesis workflow and TTS configuration	Phase 3
RECORDING.md	Screen capture settings and export procedures	Phase 4

Optional structural inspiration is available in skills/web-video-presentation/references/EXAMPLES/, though these serve as reference implementations rather than copy-paste templates.

Workflow Implementation

Phase 1: Outline and Script Development

Begin by consulting references/OUTLINE-FORMAT.md to structure the outline.md file. Convert this into a full script using the conventions in references/SCRIPT-STYLE.md, ensuring the narrative flow matches the intended visual pacing.

Phase 2: Chapter Development

During implementation, agents must read references/CHAPTER-CRAFT.md for every chapter created. Each chapter requires registration in templates/src/registry/chapters.ts and must export a narrations.ts file defining the step count and spoken text for that segment. The useStepper hook consumes this configuration to advance the presentation state.

Phase 3: Audio Synthesis

After authoring narrations, run the extraction and synthesis pipeline:

# Extract narration metadata from all chapters

npm run extract-narrations

# Generate audio using default MiniMax provider

npm run synthesize-audio

# Or use OpenAI TTS

PRESENTATION_TTS=openai npm run synthesize-audio

These commands invoke the scripts in templates/scripts/ to produce synchronized audio assets.

Phase 4: Recording

Final video capture follows the procedures in references/RECORDING.md, utilizing the clean 16:9 canvas rendered by the Stage component and the auto-play capabilities provided by useAutoMode.

Quick Start Example

Initialize a new presentation project and start the development server:

# 1. Scaffold a new project with the paper-press theme

bash skills/web-video-presentation/scripts/scaffold.sh ./my-video --theme=paper-press

# 2. Remove starter example (optional)

rm -rf my-video/src/chapters/01-example

# Edit my-video/src/registry/chapters.ts to remove the example import

# 3. Install dependencies

cd my-video
npm install

# 4. Start development server

npm run dev

The development server typically starts on http://localhost:5173. The Stage component automatically scales the 1920×1080 canvas to fit the browser, while useStepper manages navigation state.

Summary

• Core scaffold: Generated by scripts/scaffold.sh and built with Vite configuration from templates/vite.config.ts.
• UI components: Stage.tsx renders the 16:9 canvas; ProgressBar.tsx provides hover-only navigation feedback.
• State management: useStepper.ts drives the global step counter; useStageScale.ts maintains aspect ratio across viewports.
• Audio pipeline: extract-narrations.ts aggregates text; synthesize-audio.sh delegates to MiniMax or OpenAI providers.
• Theming: Token-based CSS variables in themes/*/tokens.css with metadata in themes/*/theme.json.
• Workflow guides: Six reference documents in references/ govern the four-phase creation process from outline to final recording.

Frequently Asked Questions

What file controls the step navigation in a web-video-presentation?

The useStepper hook in skills/web-video-presentation/templates/src/hooks/useStepper.ts controls the global step counter. It persists state across browser sessions and coordinates with chapter-specific narrations.ts files to determine the total step count for each section.

How do I add a custom TTS provider to the audio pipeline?

Create a new bash script following the interface defined in skills/web-video-presentation/templates/scripts/tts-providers/README.md. Place your script in templates/scripts/tts-providers/ and invoke it by setting the PRESENTATION_TTS environment variable to your provider's name before running npm run synthesize-audio.

Where is the 16:9 aspect ratio enforced in the codebase?

The Stage component in skills/web-video-presentation/templates/src/components/Stage.tsx defines the 1920×1080 presentation canvas. The useStageScale hook in templates/src/hooks/useStageScale.ts calculates the CSS transforms necessary to fit this fixed-resolution stage into the browser viewport while preserving the 16:9 aspect ratio.

Which reference document should I read first when creating a new presentation?

Start with skills/web-video-presentation/references/OUTLINE-FORMAT.md during Phase 1.2 to structure your content architecture. Follow with references/SCRIPT-STYLE.md to convert the outline into a presentable script before proceeding to chapter implementation.

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