Web-Video-Presentation Skill Working Directory Structure Explained

The web-video-presentation skill employs a rigorously organized directory structure under skills/web-video-presentation/ that separates metadata, scaffolding scripts, a reusable Vite+React template, and 23 distinct visual themes to enable rapid generation of cinematic web presentations.

The ConardLi/garden-skills repository hosts the web-video-presentation skill, which provides a complete framework for building web-based video presentations. Its working directory follows a clear segregation of concerns, partitioning documentation, automation scripts, application boilerplate, and design assets into discrete, navigable folders.

Top-Level Directory Layout

The root of skills/web-video-presentation/ contains seven primary entries that define the skill's interface and assets:

• manifest.json — Machine-readable metadata for the skill registry, declaring name, version, category, and compatibility with agent back-ends.
• SKILL.md — Formal skill specification containing metadata, version, and canonical checkpoints.
• README.md / README.zh-CN.md — Human-readable overviews with usage instructions and theme galleries.
• references/ — Design contracts and documentation anchors, including PRINCIPLES.md, CHAPTER-CRAFT.md, OUTLINE-FORMAT.md, SCRIPT-STYLE.md, THEMES.md, AUDIO.md, and RECORDING.md.
• scripts/ — Automation utilities, primarily scaffold.sh for project generation.
• templates/ — A complete, boilerplate Vite + React + TypeScript project that serves as the presentation engine.
• themes/ — A collection of 23 pre-built visual themes, each containing tokens.css and theme.json.

The Templates Directory

The templates/ folder contains the full application source that powers every generated presentation. When scripts/scaffold.sh executes, it copies this directory into the user's target folder.

React Architecture and Core Hooks

The template implements a component-based React architecture centered on presentation logic:

• src/App.tsx — Root component that mounts the presentation Stage and manages global state.
• src/hooks/useStepper.ts — Manages slide progression and navigation logic.
• src/hooks/useStageScale.ts — Handles responsive scaling of the presentation canvas.
• src/hooks/useAudioPlayer.ts — Orchestrates audio narration playback synchronized with slides.
• src/hooks/useAutoMode.ts — Enables automatic, timed progression through chapters.

UI Components

Visual primitives reside in src/components/ and consume semantic design tokens:

• Stage.tsx — Primary rendering surface for slides.
• MaskReveal.tsx — Transition component for cinematic reveal effects.
• ProgressBar.tsx — Navigation indicator showing presentation progress.
• AutoStartGate.tsx — Modal gate controlling auto-play initiation.
• AutoToggle.tsx — UI control for enabling/disabling auto-mode.

Chapter Registry System

Content organization follows a strict registry pattern:

• src/registry/types.ts — TypeScript interfaces defining chapter contracts.
• src/registry/chapters.ts — Central registration file importing all presentation chapters.
• src/chapters/01-example/ — Template chapter demonstrating file structure, containing Example.tsx, Example.css, and narrations.ts.

The Themes Directory

Located at themes/, this directory houses 23 self-contained visual design systems. Each subdirectory—such as midnight-press/, warm-keynote/, newsroom/, or bauhaus-bold/—contains exactly two files:

• tokens.css — Maps semantic variables (colors, typography, spacing) to concrete CSS values.
• theme.json — Human-readable metadata describing the theme's mood, intended use case, and design philosophy.

During scaffolding, scripts/scaffold.sh copies the selected theme's tokens.css into the generated project's src/styles/tokens.css, establishing the visual identity.

The References Directory

The references/ folder serves as the skill's knowledge base, containing formal contracts that agents consult to ensure generated content adheres to methodology:

• PRINCIPLES.md — Core design philosophy and constraints.
• CHAPTER-CRAFT.md — Checklist for creating cohesive narrative chapters.
• OUTLINE-FORMAT.md — Specification for outline structure.
• SCRIPT-STYLE.md — Guidelines for narration scriptwriting.
• AUDIO.md — Contract for the audio synthesis pipeline.
• RECORDING.md — Technical specifications for recording output.

Scaffolding Workflow

The scripts/scaffold.sh utility orchestrates project creation by integrating the directory components:

1. Accepts a TARGET directory path and optional --theme parameter.
2. Clones templates/ contents into TARGET/src/.
3. Injects the specified theme's tokens.css into TARGET/src/styles/tokens.css.
4. Registers npm scripts (extract-narrations, synthesize-audio) in TARGET/package.json.
5. Writes a .theme marker file to record the initial theme selection.

Scaffolding Commands

Generate a new presentation with the default theme:

bash skills/web-video-presentation/scripts/scaffold.sh ./my-presentation

Specify a theme explicitly:

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

List available themes:

bash skills/web-video-presentation/scripts/scaffold.sh --list-themes

Running the Generated Project

After scaffolding, navigate to the target directory and execute:

npm run dev

This starts the Vite development server (typically at http://localhost:5174).

Audio Pipeline Commands

The generated project includes automation for narration handling:

Extract narration metadata from all chapter files:

npm run extract-narrations

Synthesize audio using the default Minimax provider:

npm run synthesize-audio

Key Configuration Files

Several files define the skill's integration and build behavior:

• manifest.json — Declares compatibility with Claude, Cursor, and other agent back-ends for automatic discovery.
• templates/vite.config.ts — Vite configuration for the generated React application.
• templates/src/styles/tokens.css — Runtime CSS variables that theme files populate.
• SKILL.md — Formal specification used by agents to understand skill phases and checkpoints.

Summary

• The web-video-presentation skill resides at skills/web-video-presentation/ and separates concerns across seven top-level directories.
• templates/ provides a complete Vite+React application with hooks like useStepper and components like Stage.tsx.
• themes/ contains 23 theme packages, each with tokens.css and theme.json defining visual design systems.
• scripts/scaffold.sh automates project creation by copying templates and injecting selected themes.
• references/ stores design contracts including CHAPTER-CRAFT.md and OUTLINE-FORMAT.md to guide content generation.
• manifest.json enables machine discovery of the skill by the Opencode platform.

Frequently Asked Questions

What file defines the visual appearance of a generated presentation?

The visual appearance is controlled by src/styles/tokens.css in the generated project, which is copied from the selected theme's tokens.css during scaffolding. This file maps semantic CSS variables to concrete values for colors, fonts, and spacing.

How does the scaffold script know which theme to apply?

When running scripts/scaffold.sh, you pass the --theme=<name> flag to specify one of the 23 directories under themes/. If omitted, it uses a default theme. The script also writes a .theme file to the generated root to record the selection for future reference.

What is the purpose of the references/ directory?

The references/ directory contains mandatory design contracts and guidelines (PRINCIPLES.md, CHAPTER-CRAFT.md, AUDIO.md, etc.) that agents consult to ensure generated presentations follow the skill's methodology for structure, style, and audio integration.

Can I modify the default React components after scaffolding?

Yes. The templates/src/components/ files—including Stage.tsx, ProgressBar.tsx, and MaskReveal.tsx—are copied into your generated project and can be freely modified. These components consume the CSS tokens, so changes to styling remain centralized in tokens.css.

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