annual-report-video 🎬

English | 中文说明

⚠️ Licensing Notice This repository is made available as source-available software for personal learning, research, non-commercial evaluation, and technical exchange only. Commercial use is prohibited, including client work, internal production use, paid training, SaaS/API offerings, or any use that directly or indirectly generates revenue. For commercial licensing, contact: jiasiyuan129@qq.com

annual-report-video is a staged Claude skill that turns an annual report / earnings-summary PDF into a premium Remotion-based data-video project. It is designed for high-aesthetic financial storytelling with strict workflow gating: first extract structured data, then design the storyboard, then implement scenes in code. The skill combines creative references, deterministic validators, and QA gates so the result is not only technically stable, but also visually distinctive.

✨ What this skill does

Given a report PDF and an optional company logo, the skill can produce:

• parsed/report.md — parsed report markdown with extracted images
• data/extraction.json — structured, video-ready facts
• data/storyboard.md — scene-by-scene storyboard
• src/scenes/Scene0X.tsx — Remotion scene files
• src/FullVideo.tsx + src/Root.tsx — final composition wiring
• Studio preview info and, when explicitly requested, render/export output

This skill is optimized for:

• annual report summaries
• earnings highlights
• investor-relations materials
• financial recap videos
• Chinese-language report-to-video workflows

🧭 Operating workflow

The skill uses a gated delivery flow. It must stop at the major checkpoints instead of rushing from PDF to final code in one shot.

Step 0 — Intake & startup confirmation 📝

Before any parsing or code generation, the skill confirms:

1. Input files
   • report PDF path (required)
   • logo path (optional)
2. Aspect ratio
   • 9:16
   • 16:9
   • 1:1
3. Output directory
   • default: ./annual-report-video/
4. Color preferences (recommended to ask)
   • background base color (optional)
   • theme / accent colors (optional)
   • if unspecified, the skill falls back to a deep-blue premium tech-finance palette

Interaction design

• Aspect ratio must be confirmed.
• Color preference is optional.
• If critical startup info is missing, the skill should not start parsing the PDF yet.

Step 1 — PDF parsing 📄

The skill calls the pdf skill to:

• copy the source PDF into the project
• parse the PDF into markdown
• extract images from the PDF
• copy the optional logo into the project

Output:

• app/parsed/report.md
• app/public/images/pdf/
• app/public/images/logo/

Step 2 — Structured extraction 🧩

The skill reads references/extraction.md and converts the parsed report into data/extraction.json.

If available, it also runs:

• scripts/validate-extraction.mjs

This stage is responsible for:

• zero-hallucination extraction
• preserving trend data
• keeping core businesses as complete as possible
• keeping top-10 shareholders as complete as possible
• extracting highlights that are representative and breakthrough-oriented

Gate 1 — Extraction confirmation 🚦

After data/extraction.json is generated, the skill must stop and ask for user confirmation.

Minimum report-back

• file path
• company name
• key financial metrics
• whether 3-year / quarterly data exists
• whether product lines, dividend info, and shareholder structure look complete

Interaction design

• The user can review the extracted structure before any storyboard work begins.
• The skill must not continue to storyboard before Gate 1 is approved.

Step 3 — Storyboard design 🎞️

After Gate 1 approval, the skill generates data/storyboard.md.

It reads, in order:

1. references/storyboard.md
2. references/classic-motion-lexicon.md
3. references/visual-grammar.md

If available, it also runs:

• scripts/validate-storyboard.mjs

Creative expectations at this stage:

• one primary storytelling focus per scene
• storyboard-first creative direction
• one primary motif / primary component per scene
• at least 2 supporting mechanisms / motion treatments when appropriate
• freedom to go beyond the lexicon when stronger scene language is needed

Gate 2 — Storyboard confirmation 🚦

After data/storyboard.md is generated, the skill must stop again.

Minimum report-back

• file path
• total scene count
• theme of each scene
• major transition logic

Interaction design

• The user confirms the creative direction before code is written.
• The skill must not start implementation before Gate 2 is approved.

Gate 3 — Implementation mode choice ⚙️

Once the storyboard is approved, the skill asks the user how implementation should proceed:

1. Progressive mode (recommended)
   • implement one scene at a time
   • preview one scene at a time
2. All-at-once mode
   • write the whole codebase first
   • review later as a full set

Interaction design

• The skill should not assume all-at-once unless the user explicitly chooses it.
• Scene-level QA is still required in both modes.

Step 4 — Code implementation + QA 💻

Before writing Remotion code, the skill rereads:

1. references/storyboard.md
2. references/classic-motion-lexicon.md
3. references/visual-grammar.md
4. references/coding-guide.md
5. remotion-best-practices skill

Implementation rules include:

• implement from the approved storyboard, not by copying other projects’ scenes
• preserve the approved primary motif / primary component and supporting mechanisms
• if simplification is necessary, simplify intentionally rather than flattening the scene into a generic fallback

QA flow:

• run Scene-level QA before handing off a scene
• run Full-video QA before final export
• run scripts/check-remotion-sync.mjs before preview/render if available

Interaction design

• In progressive mode, each scene is shown only after Scene-level QA.
• In all-at-once mode, scene QA still happens internally before the full handoff.

Step 5 — Preview or export 👀

When the user wants preview / Studio

The skill should:

• start or restart Remotion Studio
• provide the local preview URL
• mention available compositions
• avoid jumping directly to rendering

When the user wants export / mp4

The skill should:

• confirm whether the target is a single scene or FullVideo
• ensure final QA / sync checks are complete
• render only when the user explicitly asks for export

🤝 Interaction design summary

🗂️ File organization & responsibility map

SKILL.md

Role: router, workflow controller, gatekeeper

Responsible for:

• trigger conditions
• startup questions
• workflow order
• Gate 1 / Gate 2 / Gate 3 behavior
• when to preview vs when to render
• which reference/script is used at each phase

references/

Role: canonical rule sources for each stage

• references/extraction.md — extraction contract and Gate 1 reporting rules
• references/storyboard.md — storyboard design contract and scene output format
• references/classic-motion-lexicon.md — motif lexicon and advanced component vocabulary
• references/visual-grammar.md — fallback visual system, default color logic, chart/layout grammar
• references/visual-qa.md — Scene-level and Full-video QA standards
• references/coding-guide.md — implementation rules, timing sync, technical stability

scripts/

Role: deterministic validators

• scripts/validate-extraction.mjs — checks extraction structure and summarizes Gate 1
• scripts/validate-storyboard.mjs — checks storyboard format and summarizes Gate 2
• scripts/check-remotion-sync.mjs — checks timing/composition sync across storyboard and Remotion code

These scripts are not creative authorities. They exist to catch structural drift early.

evals/evals.json

Role: offline regression suite 🧪

Used for skill iteration and benchmark testing.

Typical coverage includes:

• Gate discipline
• preview vs render behavior
• reference precedence
• implementation mode behavior
• lexicon usage and scene richness
• creative-fidelity QA expectations

🧱 Typical project layout

annual-report-video/
  app/
    input/
      report.pdf
      logo.png?
    parsed/
      report.md
    public/
      images/
        pdf/
        logo/
    data/
      extraction.json
      storyboard.md
    src/
      scenes/
        Scene01.tsx
        Scene02.tsx
        ...
      FullVideo.tsx
      Root.tsx
  renders/
    scenes/
    full/

🎨 Default color fallback

If the user does not specify colors:

Default background family

• #081221
• #0B1730
• #10203D

Default palette directions

Composed / premium

• #D4FC79
• #6366F1

Cyber / contrast-heavy

• #FF006E
• #00D9FF

Default behavior:

• first color = primary highlight / KPI / active signal
• second color = secondary accent / edge light / contrast color

🔒 Non-negotiable rules

• Do not skip Gate 1 / Gate 2 / Gate 3.
• Do not continue to the next stage before user approval.
• Do not let fallback grammar override user references or approved storyboard decisions.
• Do not render unless the user explicitly asks for export.
• Do not flatten rich storyboard ideas into generic card/chart/text implementations.
• Do not copy another project’s scene code and simply replace data.

🚀 Why this skill is different

This skill is intentionally more than “just use Remotion.”

It adds:

• structured extraction discipline
• storyboard gating
• lexicon-driven scene richness
• code-stage creative preservation
• post-implementation visual QA
• deterministic validators and eval coverage

That combination is what makes it suitable for premium report-to-video workflows.