# leynos/visual-storytelling-skills architecture

> Architecture diagram of the GitHub repository leynos/visual-storytelling-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leynos/visual-storytelling-skills
- Repository: https://github.com/leynos/visual-storytelling-skills

## Overview

This repository is an agent-skill pack for AI film-production preparation, with a narration phoneticizer and an OpenShot packaging CLI. Its main workflow moves from prose through continuity inventory and reference assets, shot direction and storyboard/prompt outputs, video generation and assembly, then project packaging. README documents these handoffs and optional image-generation calls; the source excerpts show the packaging CLI, project builder, and Markdown-table helper. Most skill implementations were not sampled, so their internal relationships are shown only where the README explicitly describes them.

Main entry points: [`skills/video-generator/SKILL.md`](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/SKILL.md) (Video generator), [`skills/shot-specifier/SKILL.md`](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/SKILL.md) (Shot specifier), [`skills/scene-inventory-extractor-v2/SKILL.md`](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md) (Scene extractor), [`skills/nanobanana/SKILL.md`](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/nanobanana/SKILL.md) (Nano Banana)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_story["Story preparation"]
  node_extractor["Scene extractor<br/>[SKILL.md]"]
  node_inventory["Continuity inventory<br/>[SKILL.md]"]
  node_ref_library["Reference library<br/>[SKILL.md]"]
end

subgraph group_visual["Visual development"]
  node_shot_specifier["Shot specifier<br/>[SKILL.md]"]
  node_shot_specs["Shot specifications"]
  node_storyboard["Storyboard frames"]
  node_prompt_manifest["Prompt manifest<br/>[model-routing.md]"]
  node_nanobanana["Nano Banana<br/>[SKILL.md]"]
end

subgraph group_generation["Video generation"]
  node_video_generator["Video generator<br/>[SKILL.md]"]
  node_takes["Generated takes"]
  node_assembly["Assembly order<br/>[assembly-order.md]"]
end

subgraph group_support["Supporting skills"]
  node_phoneticize["Phoneticizer<br/>[SKILL.md]"]
  node_candidate_extractor["Candidate extraction"]
  node_seedance_guide["Seedance guidance<br/>[SKILL.md]"]
  node_kling_guide["Kling guidance<br/>[SKILL.md]"]
end

subgraph group_packaging["Project packaging"]
  node_openshot_cli["Packaging CLI<br/>[cli.py]"]
  node_openshot_builder["OpenShot builder"]
  node_markdown_tables["Markdown tables<br/>[markdown_tables.py]"]
  node_openshot_project["OpenShot project"]
end

node_filmmaker(("Filmmaker"))
node_prose["Script or prose"]
node_image_mcp{{"Image MCP"}}
node_higgsfield{{"Higgsfield MCP"}}
node_tts{{"Eleven v3"}}

node_filmmaker -->|"provides script"| node_prose
node_prose -->|"submits prose"| node_extractor
node_extractor -->|"extracts continuity"| node_inventory
node_extractor -->|"generates references"| node_ref_library
node_extractor -.->|"requests images"| node_nanobanana
node_nanobanana -->|"generates images"| node_image_mcp
node_inventory -->|"informs direction"| node_shot_specifier
node_ref_library -->|"provides references"| node_shot_specifier
node_shot_specifier -->|"produces specs"| node_shot_specs
node_shot_specifier -->|"produces frames"| node_storyboard
node_shot_specifier -->|"produces prompts"| node_prompt_manifest
node_shot_specifier -.->|"requests frame work"| node_nanobanana
node_nanobanana -.->|"returns keyframes"| node_storyboard
node_shot_specs -->|"guides generation"| node_video_generator
node_storyboard -->|"provides frames"| node_video_generator
node_prompt_manifest -->|"provides prompts"| node_video_generator
node_ref_library -->|"provides references"| node_video_generator
node_video_generator -->|"submits jobs"| node_higgsfield
node_higgsfield -->|"returns clips"| node_takes
node_video_generator -->|"downloads takes"| node_takes
node_video_generator -->|"writes order"| node_assembly
node_takes -->|"selects clips"| node_assembly
node_assembly -->|"packages selections"| node_openshot_cli
node_filmmaker -->|"invokes skill"| node_phoneticize
node_phoneticize -.->|"detects candidates"| node_candidate_extractor
node_phoneticize -->|"prepares narration"| node_tts
node_filmmaker -.->|"consults guidance"| node_seedance_guide
node_filmmaker -.->|"consults guidance"| node_kling_guide
node_openshot_cli -->|"calls builder"| node_openshot_builder
node_openshot_builder -->|"reads tables"| node_markdown_tables
node_openshot_builder -.->|"writes project"| node_openshot_project

click node_extractor "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md"
click node_inventory "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md"
click node_ref_library "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md"
click node_shot_specifier "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/SKILL.md"
click node_shot_specs "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/templates/shot-spec-template.md"
click node_storyboard "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/references/storyboard-generation.md"
click node_prompt_manifest "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/references/model-routing.md"
click node_nanobanana "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/nanobanana/SKILL.md"
click node_video_generator "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/SKILL.md"
click node_takes "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/references/media-upload-and-state.md"
click node_assembly "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/templates/assembly-order.md"
click node_phoneticize "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/phoneticize/SKILL.md"
click node_candidate_extractor "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/phoneticize/scripts/extract_candidates.py"
click node_seedance_guide "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/seedance-2-deep-dive/SKILL.md"
click node_kling_guide "https://github.com/leynos/visual-storytelling-skills/blob/main/skills/kling-3-0-deep-dive/SKILL.md"
click node_openshot_cli "https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/cli.py"
click node_openshot_builder "https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/openshot_project.py"
click node_markdown_tables "https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/markdown_tables.py"
click node_openshot_project "https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/openshot_project.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extractor,node_inventory,node_ref_library toneBlue
class node_shot_specifier,node_shot_specs,node_storyboard,node_prompt_manifest,node_nanobanana toneAmber
class node_video_generator,node_takes,node_assembly toneMint
class node_phoneticize,node_candidate_extractor,node_seedance_guide,node_kling_guide toneRose
class node_openshot_cli,node_openshot_builder,node_markdown_tables,node_openshot_project,node_filmmaker,node_prose,node_image_mcp,node_higgsfield,node_tts toneIndigo
```

## Components

### Story preparation

- [Scene extractor](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md): `skills/scene-inventory-extractor-v2/SKILL.md`
- [Continuity inventory](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md): `skills/scene-inventory-extractor-v2/SKILL.md`
- [Reference library](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/scene-inventory-extractor-v2/SKILL.md): `skills/scene-inventory-extractor-v2/SKILL.md`

### Visual development

- [Shot specifier](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/SKILL.md): `skills/shot-specifier/SKILL.md`
- [Shot specifications](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/templates/shot-spec-template.md): `skills/shot-specifier/templates/shot-spec-template.md`
- [Storyboard frames](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/references/storyboard-generation.md): `skills/shot-specifier/references/storyboard-generation.md`
- [Prompt manifest](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/shot-specifier/references/model-routing.md): `skills/shot-specifier/references/model-routing.md`
- [Nano Banana](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/nanobanana/SKILL.md): `skills/nanobanana/SKILL.md`

### Video generation

- [Video generator](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/SKILL.md): `skills/video-generator/SKILL.md`
- [Generated takes](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/references/media-upload-and-state.md): `skills/video-generator/references/media-upload-and-state.md`
- [Assembly order](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/video-generator/templates/assembly-order.md): `skills/video-generator/templates/assembly-order.md`

### Supporting skills

- [Phoneticizer](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/phoneticize/SKILL.md): `skills/phoneticize/SKILL.md`
- [Candidate extraction](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/phoneticize/scripts/extract_candidates.py): `skills/phoneticize/scripts/extract_candidates.py`
- [Seedance guidance](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/seedance-2-deep-dive/SKILL.md): `skills/seedance-2-deep-dive/SKILL.md`
- [Kling guidance](https://github.com/leynos/visual-storytelling-skills/blob/main/skills/kling-3-0-deep-dive/SKILL.md): `skills/kling-3-0-deep-dive/SKILL.md`

### Project packaging

- [Packaging CLI](https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/cli.py): `tools/media-project/media_project/cli.py`
- [OpenShot builder](https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/openshot_project.py): `tools/media-project/media_project/openshot_project.py`
- [Markdown tables](https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/markdown_tables.py): `tools/media-project/media_project/markdown_tables.py`
- [OpenShot project](https://github.com/leynos/visual-storytelling-skills/blob/main/tools/media-project/media_project/openshot_project.py): `tools/media-project/media_project/openshot_project.py`

### Other components

- **Filmmaker**
- **Script or prose**
- **Image MCP**
- **Higgsfield MCP**
- **Eleven v3**

## Connections

- Filmmaker → Script or prose: provides script (evidence: `README.md`)
- Script or prose → Scene extractor: submits prose (evidence: `README.md`)
- Scene extractor → Continuity inventory: extracts continuity (evidence: `README.md`)
- Scene extractor → Reference library: generates references (evidence: `README.md`)
- Scene extractor → Nano Banana: requests images (evidence: `README.md`)
- Nano Banana → Image MCP: generates images (evidence: `README.md`)
- Continuity inventory → Shot specifier: informs direction (evidence: `README.md`)
- Reference library → Shot specifier: provides references (evidence: `README.md`)
- Shot specifier → Shot specifications: produces specs (evidence: `README.md`)
- Shot specifier → Storyboard frames: produces frames (evidence: `README.md`)
- Shot specifier → Prompt manifest: produces prompts (evidence: `README.md`)
- Shot specifier → Nano Banana: requests frame work (evidence: `README.md`)
- Nano Banana → Storyboard frames: returns keyframes (evidence: `README.md`)
- Shot specifications → Video generator: guides generation (evidence: `README.md`)
- Storyboard frames → Video generator: provides frames (evidence: `README.md`)
- Prompt manifest → Video generator: provides prompts (evidence: `README.md`)
- Reference library → Video generator: provides references (evidence: `README.md`)
- Video generator → Higgsfield MCP: submits jobs (evidence: `README.md`)
- Higgsfield MCP → Generated takes: returns clips (evidence: `README.md`)
- Video generator → Generated takes: downloads takes (evidence: `README.md`)
- Video generator → Assembly order: writes order (evidence: `README.md`)
- Generated takes → Assembly order: selects clips (evidence: `README.md`)
- Assembly order → Packaging CLI: packages selections (evidence: `README.md`)
- Filmmaker → Phoneticizer: invokes skill (evidence: `README.md`)
- Phoneticizer → Candidate extraction: detects candidates
- Phoneticizer → Eleven v3: prepares narration (evidence: `README.md`)
- Filmmaker → Seedance guidance: consults guidance (evidence: `README.md`)
- Filmmaker → Kling guidance: consults guidance (evidence: `README.md`)
- Packaging CLI → OpenShot builder: calls builder (evidence: `tools/media-project/media_project/cli.py`)
- OpenShot builder → Markdown tables: reads tables (evidence: `tools/media-project/media_project/openshot_project.py`)
- OpenShot builder → OpenShot project: writes project (evidence: `tools/media-project/media_project/openshot_project.py`)
