Communitygithub.com

YuukiMarine/websiteskills

把一篇文章或口播稿,做成"看起来像视频"的点击驱动 16:9 网页演示,可选合成口播音频。流程:原始文章 → **一次产出**口播稿 + outline 开发计划 → 用户**一次对齐** 5 件事(稿子 / outline / 主题 / 素材 / 开发模式)→ 网页开发(逐章 / 顺序 / 并行)→ 可选音频合成(provider-agnostic:内置 MiniMax mmx-cli + OpenAI TTS,可换 ElevenLabs / edge-tts / Azure / 自带 TTS)。**outline 只规划节奏与信息密度,不规划动画** —— 动画由章节开发时按 PRINCIPLES + ANTI-AI 法则即时设计。每次点击推进口播稿的一个节拍,每一步独占整屏,进度条平时隐藏只在悬浮时出现。适用场景:用网页做视频(动态 PPT 但不像 PPT)、把口播稿 / 文章变成可交互的解说、为 B 站 / YouTube / 视频号录屏教程、做有电影感的产品 / talk demo。本 Skill 沉淀的是设计方法论 + 协作流程 —— 不绑定任何特定样式 / 字体 / 颜色 —— 因此能复用到任意主题与美学。

websiteskills 是什么?

websiteskills is a Claude Code agent skill that 把一篇文章或口播稿,做成"看起来像视频"的点击驱动 16:9 网页演示,可选合成口播音频。流程:原始文章 → **一次产出**口播稿 + outline 开发计划 → 用户**一次对齐** 5 件事(稿子 / outline / 主题 / 素材 / 开发模式)→ 网页开发(逐章 / 顺序 / 并行)→ 可选音频合成(provider-agnostic:内置 MiniMax mmx-cli + OpenAI TTS,可换 ElevenLabs / edge-tts / Azure / 自带 TTS)。**outline 只规划节奏与信息密度,不规划动画** —— 动画由章节开发时按 PRINCIPLES + ANTI-AI 法则即时设计。每次点击推进口播稿的一个节拍,每一步独占整屏,进度条平时隐藏只在悬浮时出现。适用场景:用网页做视频(动态 PPT 但不像 PPT)、把口播稿 / 文章变成可交互的解说、为 B 站 / YouTube / 视频号录屏教程、做有电影感的产品 / talk demo。本 Skill 沉淀的是设计方法论 + 协作流程 —— 不绑定任何特定样式 / 字体 / 颜色 —— 因此能复用到任意主题与美学。.

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/YuukiMarine/websiteskills/tree/HEAD/skills/web-video-presentation

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Web Video Presentation

Turns an article or voiceover script into a screen-recordable "webpage disguised as a video," step by step. Optionally synthesize voiceover audio. Output = Vite + React + TS project + chapter-split audio.

Suitable Scenarios

  • "I have a voiceover script / article, help me make a video" — voiceover-driven content
  • Want to create a "dynamic PPT"
  • 16:9 landscape screen recording, large text, white space, every screen must have animation
  • Teaching / product demos / keynotes with a cinematic feel
  • Bilibili / YouTube / Douyin video content

This skill focuses on methodology + collaboration workflow. The scaffold template provides tokens and primitives, but every aesthetic decision (color scheme, font, animation style) should be redesigned for your topic — don't copy.


Workflow Overview

Phase 1   Content Writing
   1.1  Identify User Input
   1.2  One-shot output script.md + outline.md
        (voiceover script + development plan)
   ▼
[Checkpoint Plan]      ← Must stop. Align on 5 things at once:
                         Script / Outline / Theme / Assets / Dev Mode
   ▼
Phase 2   Web Development
   2.1  Scaffold (with selected theme)
   2.2  Chapter 1 = main thread + complete version (mandatory anchor)
        ▼
        [Hard Node] User reviews Chapter 1 ← Cannot skip
        ▼
   2.3  Chapters 2~N (with selected mode: A chapter-by-chapter / B sequential / C parallel)
   ▼
[Checkpoint Audio]     ← Must stop. Decide whether to synthesize audio
   ▼
Phase 3   Audio Synthesis (optional)
   ▼
Phase 4   Screen Recording + Post-production

Working directory conventions (agent creates / edits in the user's current directory):

my-video/
├── article.md          # Present when user provides original text — do not delete! Source of visual info during development
├── script.md           # Mandatory: Platform-adapted voiceover script in the original language (determines beats)
├── outline.md          # Mandatory: Development plan (chapter splits + per-step content + info pool)
└── presentation/       # Scaffolded Vite + React + TS project
    ├── src/chapters/<NN>-<id>/
    │   ├── <Chapter>.tsx     # Visual implementation
    │   ├── <Chapter>.css
    │   └── narrations.ts     # ★ Single source of truth for step count + voiceover text
    ├── scripts/
    │   ├── extract-narrations.ts   # Scans all narrations.ts → audio-segments.json
    │   ├── synthesize-audio.sh     # Provider-agnostic runner (loops over segments)
    │   └── tts-providers/          # One .sh per provider (2 built-in)
    │       ├── README.md           # Three-function contract + 5 ready-to-use code snippets (11labs / edge-tts / say / azure / gcloud)
    │       ├── minimax.sh          # Default provider, uses mmx-cli
    │       └── openai.sh           # Built-in OpenAI TTS (curl + OPENAI_API_KEY)
    ├── audio-segments.json         # Extract output (review before synthesis)
    └── public/audio/<id>/<N>.mp3   # Optional: Synthesized audio

Key: narrations.ts is the single source of truth for step count and audio synthesis. The maximum N + 1 in if (step === N) in the chapter .tsx must equal narrations.length. This ensures that 5 locations (script / outline / chapter code / chapters.ts / audio files) never drift.


Mandatory Self-Check Protocol (Throughout This Skill)

For each of the three outputs below, after completion, you must self-check → fix → then report / proceed:

OutputSelf-Check Source
script.mdSCRIPT-STYLE.md three-layer self-check (form / substance / read-aloud)
outline.mdOUTLINE-FORMAT.md self-check
Single chapter implementation completeCHAPTER-CRAFT.md completion self-check

Execution Method (descending capability, prefer the most isolated approach):

  1. Agent Teams (best): Open a separate reviewer agent, give it "output file path + corresponding checklist + key context," ask it to check item by item and strictly report conclusions (which items pass / which fail + evidence + rewrite suggestions).
  2. subAgent (next best): If no Teams capability but subagent is available, use a subagent with the same process.
  3. Self-check (fallback): If the current agent has neither capability, strictly check each item yourself — do not just glance and pass.

Iron rule: After getting the conclusion, fix the output according to the failing items first, then report to the user "done + self-check conclusion + what was fixed." Reporting the raw conclusion without fixing = violation.


Phase-by-Phase File Reading Guide

Read different files at different phases. In long sessions, the agent may forget principles, especially Phase 2.4's "implement a single chapter" which repeats N times — core constraints must be revisited each time.

PhaseMust Read (every time)Read Once / Query on Demand
Phase 1.1-1.2 Content Writingreferences/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.md (user's original text, if any)—
Checkpoint Plan Select Theme—themes/*/theme.json (read all dynamically, list + bestFor recommendation + description); references/THEMES.md (when user wants to understand the theme system)
Phase 2.1 Scaffold—SKILL.md this section once
Phase 2.4 Implement Single Chapter (×N times, called by 2.2 / 2.3)references/CHAPTER-CRAFT.md single entry — Part 0 Ten Principles / Part 1 Start-up 5 Questions / Part 2 Relationship→Action Decision Tree / Part 3 Visual Toolkit / Part 4 Duration Reference / Part 5 Anti-AI Anti-Patterns / Part 6 Code Hard Rules (including narrations.ts mandatory constraints) / Part 7 Completion Self-Check / Part 8 Feedback Quick Reference + current theme's themes/<id>/theme.json + current chapter's outline.md paragraph + article.md corresponding paragraph for this chapter + asset listreferences/EXAMPLES/ (structural reference, not a template to copy); references/THEMES.md complete token contract
Phase 3 Audio Synthesisreferences/AUDIO.md (includes narrations.ts → segments.json → arbitrary provider workflow, built-in minimax + openai)templates/scripts/tts-providers/README.md (when changing providers / using custom TTS)
Phase 4 Screen Recording + Post-productionreferences/RECORDING.md (includes ?auto=1 auto-recording)—
Select / Create / Customize Theme—references/THEMES.md

When writing chapters, read only one CHAPTER-CRAFT.md. Ten Principles / start-up self-prompting / Decision Tree / Anti-AI Anti-Patterns / Completion Self-Check all merged into this single entry. EXAMPLES/ is not mandatory — design freely based on content first, only refer when stuck (refer to "shape," not copy).


Phase 1 — Content Writing (One-Shot Output)

1.1 Identify User Input

What the User ProvidesWhat to Do
Original article (written language / WeChat public account / thesis / blog)One-shot output script.md + outline.md (1.2), go to Checkpoint Plan
Direct voiceover script / video scriptSave as script.md, one-shot output outline.md (simplified 1.2), go to Checkpoint Plan
Nothing, just says "Help me make a video on topic X"Ask back: Provide some material or an outline first. This skill does not invent content for the user

1.2 One-Shot Output script.md + outline.md

Produce both outputs in one thinking session:

  1. Generate script.md: According to the rules in references/SCRIPT-STYLE.md, convert the article into a platform-adapted voiceover script in the original language. Keep article.md — do not delete — it is the source of detail for the info pool in the outline and for visuals during chapter implementation (dual-source principle).
  2. Generate outline.md: According to the rules in references/OUTLINE-FORMAT.md, split into chapters + split into steps + extract the info pool from the first paragraph of each chapter.

Boundaries of the outline (key):

What outline MUST writeWhat outline MUST NOT write
Chapter splits / steps per chapter / estimated timeSpecific animation types (blur clear / wipe / spring)
Per-step screen content (hero / data / tagline / list items)CSS implementation details (filter / SVG / clip-path)
Chapter-level info pool: numbers / quotes / cases / tags extracted from articleDuration values (don't write 2.5s / 80120ms)
Step-level relationship prefix ("contrast" / "progressive list" / "key quote" etc. optional hints)Micro-rhythm like persistent micro-animations / staggered timing

Reason outline doesn't write animations: Hardcoding animations reduces the chapter agent to a translation machine; leaving them blank allows the chapter agent to freely design at each step using the "content-driven decision tree" from CHAPTER-CRAFT.md , achieving a true video feel. See CHAPTER-CRAFT.md Part 0 Principle 7.

After saving, must self-check before proceeding to Checkpoint Plan: Execute the "Mandatory Self-Check Protocol" above for script.md / outline.md respectively (prioritize Agent Teams → subAgent → self-check), fix according to conclusions, then enter Checkpoint Plan.


Checkpoint Plan — Align on 5 Things at Once (Hard Node)

After script.md + outline.md are written, you must stop. The user confirms 5 things at this single node.

Agent's Preparation at This Point

  1. Read all themes/*/theme.json to get name / description / bestFor / mood — do not hardcode the list
  2. Based on the content type / keywords / tone of script.md, proactively pick 2~3 best-matching recommendations from the themes (match the bestFor field)
  3. Scan the "Asset List" section at the end of outline.md

Summary Template (skeleton, agent fills as appropriate)

Content plan written, output files:
  📄 article.md     {if user provided original text, keep}
  📄 script.md      {X} characters / ~{T} minutes
  📄 outline.md     {N} chapters / {M} steps + per-chapter info pool + asset list at end

Chapter overview:
  1. <id>     <chapter title>    <S> steps ~<T>s
  2. ...

Next, align on 5 things at once:

  1. Script (script.md) — any changes needed?
     You can edit the file directly, or verbally tell me the direction.

  2. Development plan (outline.md) — any changes needed? Key points:
     - Are chapter splits / step counts / estimated times reasonable (reasonable = ~30~60s per chapter)
     - Is per-step screen content clear
     - Does the first paragraph "info pool" of each chapter have enough article details for visuals
     - Is the asset list at the end complete

  3. Which theme to choose? My recommendations:
     ★ <Recommendation 1: name (id)> — because <bestFor match>; <description summary>
     ★ <Recommendation 2 / 3>
     Other options: <remaining themes, name + one-liner>
     You can also ask me to create a new theme (see references/THEMES.md).

  4. How to prepare real assets? Rough list of images needed for this video: <rough list>
     a) I pick from <existing asset path>   b) You provide them yourself   c) All placeholders

  5. Which development mode to choose?

     **Chapter 1, regardless of mode, must be done on the main thread + user reviewed** (mandatory anchor).
     Difference starts from Chapter 2 onwards:

     A) Default · Chapter-by-chapter confirmation (recommended)
        Pause and review after each chapter → risk controllable / most stable pace
     B) Sequential development after Chapter 1 (not parallel)
        Chapters 2~N done sequentially on the main thread, then reviewed all at once → moderate speed / good for agents that don't support parallel
     C) Parallel development after Chapter 1 (subagent)
        Chapters 2~N done in parallel using subagents → fastest / user controls max concurrency (how many chapters at once)
        ⚠️ Style may vary between chapters (expected — themes provide a safety net)

After receiving feedback:

  • If script / outline needs changes: edit the files directly, ping once after editing (or verbally describe, agent edits)
  • Theme must be explicitly decided before entering Phase 2. User says "You choose the theme for me" → take your first recommendation, tell the user what you chose and why, give them a chance to undo
  • Mode selected → enter Phase 2

Phase 2 — Web Development

2.1 Scaffold

bash <path-to-web-video-presentation>/scripts/scaffold.sh \
  ./presentation \
  --theme=<user's selected theme id>

bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes

Custom theme → first follow the "Create New Theme" process in references/THEMES.md to create a themes/<my-theme>/, then --theme=<my-theme>.

The scaffold includes a 01-example demo. Delete it before writing real content for Chapter 1:

rm -rf presentation/src/chapters/01-example

Also remove the EXAMPLE_CHAPTER import and array entry in presentation/src/registry/chapters.ts.

2.2 Chapter 1 — Main Thread + Mandatory Review

Core: Chapter 1 = complete version done right in one go (rhythm + visuals + real assets complete). No "skeleton version" concept — Chapter 1 must be a user-reviewable prototype.

Why Chapter 1 must be on the main thread:

  • It is the first application of the CHAPTER-CRAFT.md guidelines with the current theme + current subject matter
  • If there are blind spots / theme colors or font tokens insufficient, Chapter 1 will expose them — fixing early with human feedback costs the least
  • Subsequent chapters (sequential or parallel) will use Chapter 1's code pattern as reference, so Chapter 1 = the "style anchor" of the project (don't force uniformity between chapters, but the chapter itself must be fully convincing)

After completing Chapter 1, you must stop and wait for user review:

Chapter 1 <id> is done. Dev server running at localhost:5173.

Review focus:
  □ Is the visual vibe correct? Does it match the expectations of <theme name>?
  □ Is the rhythm correct? Any steps too fast / too slow / too thin on info?
  □ Are content-driven animations in place? Or are some steps just mindless entrance animations?
  □ Dual-source principle: Does the screen have details that "the voiceover doesn't mention but the article can hang"?
  □ Anti-AI feel check: Purple-pink gradients / rounded color borders / fake illustrations / emoji overuse?

Tell me what needs fixing. Say "continue" when ready, and I'll proceed with Chapters 2+ in the selected mode.

2.3 Chapters 2~N — According to Selected Mode

Common rules for all modes: Each chapter is developed independently according to CHAPTER-CRAFT.md. Style does not need to be perfectly uniform between chapters — theme colors / font tokens provide visual cohesion; animation / rhythm / visual demonstrations freely expressed per chapter is the design expectation.

Mode A · Default · Chapter-by-Chapter Confirmation

Chapter 2 done → pause and review → OK → Chapter 3 → pause → ... → Chapter N. Each chapter reviewed independently, issues can be fixed anytime, lowest risk, most stable pace. This is the default if the user doesn't explicitly select a mode.

Mode B · Sequential Development After Chapter 1

Chapter 2 → Chapter 3 → ... → Chapter N done sequentially on the main thread, reviewed all at once at the end. Moderate speed, suitable for environments where the agent doesn't support parallel tasks.

Mode C · Parallel Development After Chapter 1 (subagent)

Use subagents to complete Chapters 2~N in parallel. Maximum parallelism controlled by the user ("4 chapters at once" / "2 chapters at once"). Fastest, but style may vary between chapters — this is expected, because:

  1. Each subagent doesn't see other subagents' output and can't mechanically align
  2. Chapter code is physically separated (each chapter has its own folder / CSS prefix), they won't interfere
  3. Theme tokens provide visual cohesion (colors / fonts / hero numbers / cards / divider styles / decorations), preventing severe deviation
  4. Style variation = the breathing feel of hand-crafted video (multi-voice / multi-perspective)

The parallel subagent prompt must include:

  • The current chapter's outline paragraph (with info pool)
  • Path to references/CHAPTER-CRAFT.md (singular mandatory read — visual demonstration requirements + step-by-step reveal + dual-source principle + anti-AI feel + code red lines + completion self-check all in this one file)
  • Current theme's theme.json description / mood / bestFor (reference for vibe only; animations / duration / font sizes / emojis are at the chapter agent's discretion)
  • Chapter 1's code as a "code style" reference (not a "visual copy target")
  • Hard rules: Each chapter has its own CSS prefix (.cd- / .mg- / .pm- / ...); do not modify chapters.ts; on completion, run npx tsc --noEmit

Important: Regardless of mode selected, the user can switch modes at any time. After Chapter 2 is OK, the user can say "parallel the rest" / "sequential the rest."

2.4 Implement a Single Chapter (Mandatory Per Chapter)

Detailed guidance in references/CHAPTER-CRAFT.md — single mandatory read entry, covering: visual demonstration requirements / step-by-step reveal / content curation / dual-source principle / basic video demo aesthetics / anti-AI feel / code red lines / completion self-check.

Core Points (detailed in CHAPTER-CRAFT.md):

  • Every chapter must have CSS / SVG / Canvas / JS visual demonstrations, no pure-text chapters allowed
  • Step-by-step reveal: Lists / multi-item displays must have 1 item = 1 step, forbid showing all at once
  • Dual-source principle: Rhythm follows the voiceover script (order cannot be changed), details revisit the original article (info pool + this chapter's article paragraph)
  • Go through the completion self-check item by item; if not meeting standards, go back and fix — execute according to the "Mandatory Self-Check Protocol" above (prefer Agent Teams → subAgent → self-check), only then report this chapter's delivery to the user

2.5 Bump STORAGE_KEY After Major Changes

After modifying chapters.ts (adding / deleting / rearranging chapters, or changing narrations.ts length in a chapter), bump STORAGE_KEY in presentation/src/hooks/useStepper.ts (e.g., v4 → v5) to prevent the persisted cursor from landing on a non-existent step.


Checkpoint Audio — Whether to Synthesize Audio (Hard Node)

After Phase 2 ends, you must stop and ask the user:

Web presentation done, {N} chapters / {M} steps. Dev server running at localhost:5173.

Would you like to synthesize audio for "auto-play screen recording"?
  ✓ Yes → Scan all chapters' narrations.ts to produce audio-segments.json,
            call TTS provider to synthesize each step as an mp3 into public/audio/.
            After synthesis, use ?auto=1 mode for one-shot screen recording (audio/video naturally synced).
            Two built-in providers:
             • minimax (mmx-cli)    — default, stable for Chinese voice
             • openai  (OPENAI_API_KEY) — curl-based, most users already have a key
            Other backends (ElevenLabs / edge-tts free / macOS say offline /
            Azure / Google) — see ready-made snippets in scripts/tts-providers/README.md.
  ✗ No → Skip Phase 3, go directly to Phase 4 for manual recording + post-production voiceover.

If synthesis → Phase 3. If no → directly Phase 4.


Phase 3 — Audio Synthesis (Optional)

Detailed process in references/AUDIO.md. Simplified:

cd presentation
npm run extract-narrations   # Scan all narrations.ts → audio-segments.json
# Let user review audio-segments.json to confirm text correctness
npm run synthesize-audio                       # Default minimax provider, incremental
# Or use built-in openai (requires OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# Or custom: write a scripts/tts-providers/<name>.sh, see README.md in that directory

After synthesis, inform the user: output location / total segments / any segments with abnormal duration (too long = step needs splitting; too short = text too thin) — give a final chance to calibrate rhythm. Then proceed to Phase 4.


Phase 4 — Screen Recording + Post-production

See details in references/RECORDING.md. Two paths:

ScenarioRecommended Path
Phase 3 audio synthesizedAuto mode one-shot recording: Open localhost:5173/?auto=1 in browser → press SPACE → video plays automatically to the end → stop recording → trim starts/ends → done, no post-production audio sync
Phase 3 skippedDefault Manual mode: Click to advance step by step → post-production, add audio in any editing tool

After Phase 3 / Checkpoint Audio, the agent should proactively tell the user the suitable recording path.


Ten Principles (One-Liner List)

Full expansion in references/CHAPTER-CRAFT.md Part 0 — Check there when writing chapters; this is just an index.

#PrincipleOne-Liner
116:9 Fixed StageContent in 1920×1080 + transform scale, no responsiveness
2Global Step CounterChapter is a pure function of step, no timers
3Each Step Occupies Full Screenif (step === N) return <FullScene />
4Voiceover Beat = StepOne beat = one step = one focused idea
5Hidden Corner ControlsProgress bar / navigator default opacity 0
6Stage Has No ChromeNo header / footer / page number / branding bar
7Content-Driven AnimationFind the intrinsic action first; only fallback to entrance animation if none; use persistent micro-animations sparingly
8Step-by-Step Reveal1 item = 1 step, forbid simultaneous stagger of N items
9Same Theme ThroughoutNo color-switching between chapters; colors / fonts via tokens, other scales free per chapter
10Dual-Source Principlescript sets the beat, article determines visual density (landing in the info pool)

Common User Feedback Quick Reference

Simplified table in references/CHAPTER-CRAFT.md Part 8 "Common Feedback Quick Reference." Key: First identify the layer (rhythm / visuals / content / code), then modify the smallest slice, don't redo the whole chapter.


Related Resources

Labelled by "when to read" to avoid reading everything at once:

FileWhen to ReadContent
references/SCRIPT-STYLE.mdPhase 1.2 mandatory readArticle → voiceover script rules, platform variants
references/OUTLINE-FORMAT.mdPhase 1.2 mandatory readoutline.md field spec, naming conventions, chapter splits, info pool
references/CHAPTER-CRAFT.mdPhase 2.4 every chapter single mandatory read entryPart 0 Ten Principles / Part 1 Start-up 5 Questions / Part 2 Relationship→Action Decision Tree / Part 3 Visual Toolkit / Part 4 Duration / Part 5 Anti-AI Anti-Patterns / Part 6 Code Hard Rules / Part 7 Completion Self-Check / Part 8 Feedback Quick Reference
references/EXAMPLES/Optional — look at structureChapter structure examples (hook / list-reveal / case-tech-review); not templates to copy
references/THEMES.mdWhen selecting / creating / customizing themesComplete token contract + built-in theme list + creation process
references/AUDIO.mdRead only in Phase 3Provider-agnostic audio synthesis workflow, built-in minimax usage, provider change path, troubleshooting
templates/scripts/tts-providers/README.mdWhen changing / adding TTS providerThree-function contract + 2 built-in (minimax / openai) + 5 ready-made code snippets (ElevenLabs / edge-tts / macOS say / Azure / Google)
references/RECORDING.mdRead only in Phase 4Screen recording tools + post-production synthesis
themes/Browse at Checkpoint Plan / Phase 1.2Built-in themes (each with theme.json + tokens.css)
scripts/scaffold.shRun once at Phase 2.1One-click project scaffold

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能