Cinematic Director Skill

A Claude Code / Claude Agent skill that turns a script, a paragraph of prose, or a single keyframe into a complete production plan — beats, director's book, blocking, shot list with coverage, keyframe prompts, image-to-video motion prompts, a sound plan, an edit timeline, a continuity bible, and a coded QC repair loop. Optionally apply one of twenty director-style lenses as a coherent overlay across the entire pass.

中文版本

Why this exists

Most "cinematic" AI prompts are adjective soup — cinematic, dramatic, masterpiece, 8K. They don't tell a model where the camera is, what the body is doing, where the action ends, or which anchors must not drift. The result is the slideshow look: pretty stills that wander between shots.

This skill replaces adjective soup with directorial reasoning:

• A shot is a story decision, not a style descriptor. If you can't say what the audience now understands that they didn't a second ago, the shot gets cut.
• Blocking comes before framing. Camera placement follows what bodies do in space. A well-blocked scene reads even shot flat.
• The keyframe is the control point. A video model mostly re-animates what the still already decided. Fixing the still is cheaper than retrying the video.
• Continuity is engineered, not hoped for. Identity strings, light direction, screen direction, and era locks are written once and repeated verbatim.
• Failures get diagnosed, not re-rolled. Nineteen coded failure modes, each with its mechanism, its ranked causes, and the cheapest fix that addresses it.
• Style is a lens, not a costume. Choosing Kubrick means wide-angle one-point perspective pressing people into architecture — not "add a zoom."

What's new in 2.0

v1 knew the vocabulary of directing. v2 knows the craft behind it.

Also new: lens and focal-length psychology, lighting ratios, continuity geometry (axis of action, the 30° rule, screen direction, eyeline match) with the AI-specific problem that a video model has no idea where the last shot put the camera, a staging-geometry library, per-genre playbooks, a controlled prompt lexicon with an EN↔中文 term table, and the operational side — shot difficulty scoring, retry budgets, versioning, and handoff.

See CHANGELOG.md for the full list. The step renumbering (10→13) and mode renumbering (A–F→A–J) are breaking changes.

Architecture

┌────────────────────────────────────────────────────────────────────────┐
│  SKILL.md — always loaded, deliberately lean                           │
│                                                                        │
│    routing table:  request type → output mode → files to load          │
│    hard rules · intake schema · defaults · self-check                  │
│                                                                        │
│    1  Intake & scope           8  Keyframe strategy                    │
│    2  Script & subtext         9  Tool adapter selection               │
│    3  Beat map                10  AI video prompt construction         │
│    4  Style lens (optional)   11  Sound & dialogue plan                │
│    5  Director's book         12  Edit & assembly plan                 │
│    6  Blocking & staging      13  QC & repair loop                     │
│    7  Shot list & coverage                                             │
└────────────────────────────────────────────────────────────────────────┘
                    │ loads on demand, never all at once
        ┌───────────┴────────────────────────────────┐
        ▼                                            ▼
┌───────────────────────────────┐      ┌─────────────────────────────┐
│ references/                   │      │ assets/  (fill-in templates)│
│   craft                       │      │   beat-sheet          Mode B│
│     cinematic-language        │      │   director-book       Mode C│
│     blocking-and-staging      │      │   shot-plan           Mode D│
│     lighting-and-color        │      │   keyframe-prompt     Mode E│
│     sound-and-dialogue        │      │   video-prompt        Mode F│
│     editing-and-assembly      │      │   sound-plan          Mode H│
│     genre-playbooks           │      │   edit-timeline       Mode I│
│     product-and-macro         │      │   qc-checklist        Mode J│
│   generation                  │      └─────────────────────────────┘
│     prompt-lexicon            │
│     ai-video-tool-adapters    │
│     image-model-adapters      │      ┌─────────────────────────────┐
│     failure-modes             │      │ evals/evals.json            │
│   production                  │      │   behavior contract         │
│     continuity-bible   Mode G │      └─────────────────────────────┘
│     production-workflow       │
│   director_styles/  20 lenses │
└───────────────────────────────┘

One skill, optional style overlay. SKILL.md is always the entry point. When the user names a director, Step 4 loads exactly one style file, and its 风格参数 YAML block overrides defaults at Steps 5, 7, 8, and 10. Style files are reference modules — they are not separately registered skills, so the host agent never has to disambiguate.

Installation

Skill files live in ~/.claude/skills/<skill-name>/ (user-level) or .claude/skills/<skill-name>/ (project-level). The folder name must match the name: field in SKILL.md (cinematic-director).

git clone https://github.com/wuwangzhang1216/DirectorSKILL.git ~/.claude/skills/cinematic-director

git clone https://github.com/wuwangzhang1216/DirectorSKILL.git .claude/skills/cinematic-director

Reload Claude Code (or your host agent) and the skill becomes available.

Quick start

Plain directorial pass

You: Turn this into a 4-shot AI video plan for Runway, 16:9.
     "A courier hesitates outside a Republican-era Shanghai apartment door
      before knocking, then slips an envelope under it and walks away."

Produces: beat map → director's book with invariant clauses → shot list (story function, size, lens, angle, camera, blocking start→motion→end, light direction, continuity anchors, risk) → Runway-shaped motion prompts → QC notes.

With a director-style overlay

You: Same scene, but direct it in the style of Wong Kar-wai.

Step 4 loads references/director_styles/09_wong_kar_wai.md and its parameter block overrides the defaults: handheld in narrow corridors, neon practicals, frame-within-frame through doorways, a step-printed beat on the slip-and-leave, voice-over from the courier, a shorter average shot length. Same four shots, a different film.

Repairing a failed clip

You: My generation looks like a slideshow — character barely moves, rain is
     frozen. Diagnose and rewrite this prompt: [paste prompt]

Runs the triage tree, names the failure code and its mechanism, then applies the cheapest fix on the cost ladder that actually addresses it — and tells you when the answer is to re-plan the shot rather than rewrite the prompt again.

Cutting what you already generated

You: I have 8 clips. Two don't match. Give me an edit plan.

Mode I: a timeline with in/out points, trim handles, transitions built from paired last/first frames, a continuous audio bed under the whole sequence, and the specific fix-in-edit patch for the two that don't match.

Director style overlays

Each module carries a bilingual one-line lens, a 反例 / What this lens is NOT section naming the adjacent styles it gets confused with and the mechanical difference, a machine-readable 风格参数 YAML block (lens kit in mm, allowed and forbidden camera moves, motion budget, key ratio, palette, average shot length, sound policy, negative-prompt additions), three prompt templates, and a worked example. Every module directs the same control scene, so the twenty read as twenty answers to one question. Index and structure: references/director_styles/README.md.

See it in action. references/director_styles/example_comparisons.md renders one scene under several lenses back to back — the fastest way to feel what an overlay actually changes.

Tool adapters

The pipeline writes directorial intent; Step 9 reshapes it for the target model. v2 leads with capability-first routing so the file survives vendor churn: identify which control surfaces a tool exposes, then pick one of four prompt shapes — S1 motion-only, S2 full-description, S3 keyframe-pair, S4 multi-shot timestamped.

Video model families covered in references/ai-video-tool-adapters.md: Runway, Veo, Kling 可灵, Luma, Sora-class, Hailuo/MiniMax, Pika, Vidu, Midjourney Video, 即梦/Dreamina/Seedance, 万相 Wanxiang, and open-source/ComfyUI-class models.

Image model families covered in references/image-model-adapters.md: Midjourney, Flux, Nano Banana/Gemini-image class, Seedream/即梦 image, Qwen-Image, SDXL + ControlNet, Ideogram, Recraft — plus the character and location consistency playbooks that make keyframes hold across a scene.

Both files describe capability classes, not live feature lists. Vendors change limits constantly; verify against current docs.

Output modes

Modes combine. A full production pass is A→B→C→D→E→F→H→I with G underneath and J at the end.

Repository structure

cinematic-director/
├── SKILL.md                              # Main pipeline: 13 steps, modes A-J, routing table
├── README.md                             # This file
├── CONTRIBUTING.md                       # How to add directors / adapters / genres / failure codes
├── CHANGELOG.md                          # Release history
├── LICENSE                               # MIT
├── references/
│   ├── cinematic-language.md             # Shot grammar, lenses, focus, continuity geometry, coverage, format
│   ├── blocking-and-staging.md           # Staging geometry, proxemics, notation, AI motion reliability
│   ├── lighting-and-color.md             # Setups, ratios, practicals, time of day, palettes, grading
│   ├── sound-and-dialogue.md             # Sound layers, dialogue for AI video, music brief, VO
│   ├── editing-and-assembly.md           # Pacing math, cut motivation, transition engineering, timeline
│   ├── genre-playbooks.md                # Per-genre directorial defaults
│   ├── product-and-macro.md              # Product, packshot, cosmetics, food, macro
│   ├── prompt-lexicon.md                 # Verb banks, replacement table, negatives, EN/中文 terms
│   ├── failure-modes.md                  # Coded manual F1-F19, cost ladder, three-strike rule
│   ├── ai-video-tool-adapters.md         # Video model surfaces, prompt shapes S1-S4
│   ├── image-model-adapters.md           # Image model surfaces, character/location consistency
│   ├── continuity-bible.md               # Character/location/prop/shot schemas + worked example
│   ├── production-workflow.md            # Operating loop, difficulty rubric, versioning, handoff
│   └── director_styles/                  # 20 style overlays + index + comparisons
├── assets/
│   ├── beat-sheet-template.md            # Mode B
│   ├── director-book-template.md         # Mode C
│   ├── shot-plan-template.md             # Mode D
│   ├── keyframe-prompt-template.md       # Mode E
│   ├── video-prompt-template.md          # Mode F
│   ├── sound-plan-template.md            # Mode H
│   ├── edit-timeline-template.md         # Mode I
│   └── qc-checklist.md                   # Mode J
└── evals/
    └── evals.json                        # Behavior contract

Extending

• Add a director: references/director_styles/NN_<slug>.md using the v2 section structure, with a filled 风格参数 block and the shared control scene; then register in four places.
• Add a video or image tool: append an adapter block plus a matrix column. No SKILL.md change needed unless the tool shifts a global default.
• Add a genre: append a block to references/genre-playbooks.md using the same fixed field set, plus a row in the comparison table.
• Add a failure code: F-codes are append-only; add F19+ with symptom, ranked causes, cost-ordered fixes, and a before/after pair.
• Add an output mode: only if genuinely distinct from A–J.
• Add an eval: append a case to evals/evals.json.

Full contributor guide: CONTRIBUTING.md.

Usage rule and disclaimer

The director-style modules describe high-level methods — narrative tendencies, camera grammar, lighting logic, editing rhythm, sound, performance, transferable checklists. They are not licensed to copy specific shots, dialogue, characters, plots, or any other copyrighted expression from any director's actual films. Use them as lenses that inform original work.

Tool adapters describe capability classes observed at the time of writing. AI video and image platforms change limits, parameters, and features constantly — always verify against the vendor's current documentation before relying on a specific behavior.

License

MIT — see LICENSE.

The MIT grant covers the skill files. The usage rule above governs how you apply the directorial knowledge with respect to existing films, which is a separate concern from software licensing.

Cinematic Director Skill（中文版本）

一个 Claude Code / Claude Agent skill：把剧本、一段散文或一张关键帧，转化为完整的制作方案——节拍表、导演书、走位、含覆盖策略的分镜表、关键帧提示词、图生视频动作提示词、声音方案、剪辑时间线、连贯性圣经，以及带编码的 QC 修复流程。可叠加 20 位导演风格中的任意一位，作为贯穿全流程的统一镜头。

为什么需要它

大多数"电影感"AI 提示词只是形容词堆砌——cinematic、dramatic、masterpiece、8K。它们不告诉模型镜头在哪、身体在做什么、动作终点在哪、哪些锚点不能漂移。结果就是 PPT 感：每张静帧都好看，镜头之间却在游走。

本 skill 把形容词堆砌替换为导演式推理：

• 镜头是叙事决策。说不出"观众此刻比一秒前多懂了什么"，这个镜头就删掉。
• 走位先于构图。摄影机位置取决于身体在空间中的动作；走位对了，平拍也能读懂。
• 关键帧才是控制点。视频模型基本上是在重新驱动静帧已经决定的一切。修静帧比重跑视频便宜得多。
• 连贯性是设计出来的。身份串、光位、画面方向、年代锁定写一次，然后逐字复用。
• 失败要诊断，不要重摇。19 个编码失败模式，每个都有机制、按概率排序的成因和成本最低的有效修复。
• 风格是镜头，不是外套。选库布里克意味着用广角单点透视把人压进建筑——不是"多加个推镜"。

2.0 有什么新东西

v1 掌握的是导演的词汇，v2 掌握的是词汇背后的手艺。

另外新增：焦距心理学、光比、连贯性几何（动作轴线、30 度规则、画面方向、视线匹配）以及"视频模型根本不知道上一镜机位在哪"这个 AI 专属难题的解法、调度几何库、类型片手册、受控提示词词库（含中英术语对照表），以及运营侧内容——镜头难度评分、重试预算、版本管理和交付包。

完整列表见 CHANGELOG.md。步骤重编号（10→13）与模式重编号（A–F→A–J）是破坏性变更。

架构

┌────────────────────────────────────────────────────────────────────────┐
│  SKILL.md — 始终在上下文里，刻意保持精简                                 │
│                                                                        │
│    路由表：需求类型 → 输出模式 → 该加载哪些文件                          │
│    硬规则 · 输入 schema · 默认值 · 自检清单                              │
│                                                                        │
│    1  需求梳理与范围        8  关键帧策略                                │
│    2  剧本与潜文本          9  工具适配器选择                            │
│    3  节拍图               10  AI 视频提示词构造                         │
│    4  导演风格镜头（可选）  11  声音与对白方案                            │
│    5  导演书               12  剪辑与合成方案                            │
│    6  走位与调度           13  QC 与修复                                 │
│    7  分镜表与覆盖策略                                                   │
└────────────────────────────────────────────────────────────────────────┘
                    │ 按需加载，绝不一次全读
        ┌───────────┴────────────────────────────────┐
        ▼                                            ▼
┌───────────────────────────────┐      ┌─────────────────────────────┐
│ references/                   │      │ assets/   可填写模板         │
│   手艺                        │      │   节拍表            Mode B  │
│     cinematic-language        │      │   导演书            Mode C  │
│     blocking-and-staging      │      │   分镜表            Mode D  │
│     lighting-and-color        │      │   关键帧提示词      Mode E  │
│     sound-and-dialogue        │      │   视频提示词        Mode F  │
│     editing-and-assembly      │      │   声音方案          Mode H  │
│     genre-playbooks           │      │   剪辑时间线        Mode I  │
│     product-and-macro         │      │   QC 清单           Mode J  │
│   生成                        │      └─────────────────────────────┘
│     prompt-lexicon            │
│     ai-video-tool-adapters    │
│     image-model-adapters      │      ┌─────────────────────────────┐
│     failure-modes             │      │ evals/evals.json            │
│   制作                        │      │   行为契约                   │
│     continuity-bible   Mode G │      └─────────────────────────────┘
│     production-workflow       │
│   director_styles/  20 位导演 │
└───────────────────────────────┘

一个 skill，可选风格叠加。 SKILL.md 始终是入口。用户点名导演时，Step 4 只加载一个风格文件，其 风格参数 YAML 块覆盖 Step 5 / 7 / 8 / 10 的默认值。风格文件是参考模块——它们不会被宿主 agent 单独注册为 skill，不会产生歧义。

安装

skill 文件放在 ~/.claude/skills/<skill-name>/（用户级）或 .claude/skills/<skill-name>/（项目级）。文件夹名必须与 SKILL.md 的 name: 一致（cinematic-director）。

git clone https://github.com/wuwangzhang1216/DirectorSKILL.git ~/.claude/skills/cinematic-director

git clone https://github.com/wuwangzhang1216/DirectorSKILL.git .claude/skills/cinematic-director

重新加载 Claude Code（或你的宿主 agent）即可触发。

快速开始

纯导演式流程

你：把这段做成 Runway 的 4 镜头 AI 视频方案，16:9。
    "民国上海，一个信差在一户公寓门口犹豫，敲了一下门，又把信封从门缝塞进去，转身离开。"

输出：节拍图 → 含不变量条款的导演书 → 分镜表（叙事功能、景别、焦距、角度、镜头运动、起-动-止走位、光位、连贯性锚点、风险）→ Runway 形态的动作提示词 → QC 注记。

叠加导演风格

你：同一场戏，用王家卫的风格来拍。

Step 4 加载 references/director_styles/09_wong_kar_wai.md，用它的参数块覆盖默认值：狭窄走廊的手持、霓虹实用光源、门框构成的画中画、塞信离开这一拍的抽格慢动作、信差的独白、更短的平均镜头长度。同样 4 个镜头，另一部电影。

修复失败的生成

你：我生成的片子像 PPT——人物几乎不动，雨是静止的。诊断并重写这条提示词：[粘贴提示词]

先跑分诊树，指出失败编码和具体机制，再沿成本阶梯用最便宜且真正对症的修复——并且会在正确答案是"重排这个镜头"而不是"再改一次提示词"时直接说出来。

把已经生成的素材剪起来

你：我有 8 段素材，其中两段接不上。给我一个剪辑方案。

Mode I：带出入点、留头留尾、由配对首尾帧构造的转场、贯穿整段的连续声床的时间线，以及那两段接不上的素材的具体补救方案。

导演风格清单

每个模块都带一句话双语镜头、反例：这不是什么（点名容易混淆的相邻风格并说明机制上的差别）、可被程序读取的 风格参数 YAML 块（镜头包毫米数、允许与禁止的机位运动、运动预算、光比、色板、平均镜头长度、声音策略、负面词补充）、三段提示词模板和一个落地示例。所有模块都执导同一个对照场景，于是这 20 个文件读起来就是同一个问题的 20 种答案。索引与结构见 references/director_styles/README.md。

看实际效果：references/director_styles/example_comparisons.md 把同一场戏用多个镜头连续处理一遍，是感受 overlay 到底改变了什么最快的方式。

工具适配器

流水线产出的是导演意图，Step 9 把它整形成目标模型的输入。v2 以能力优先路由开头，这样文件不会被厂商迭代冲垮：先确认工具暴露了哪些控制面，再从四种提示词形态里选一种——S1 纯运动、S2 全描述、S3 首尾帧、S4 多镜头时间戳。

references/ai-video-tool-adapters.md 覆盖的视频模型家族：Runway、Veo、可灵 Kling、Luma、Sora 类、海螺 MiniMax、Pika、Vidu、Midjourney Video、即梦/Dreamina/Seedance、万相 Wanxiang，以及开源/ComfyUI 类模型。

references/image-model-adapters.md 覆盖的图像模型家族：Midjourney、Flux、Nano Banana / Gemini 图像类、Seedream / 即梦图像、Qwen-Image、SDXL + ControlNet、Ideogram、Recraft——以及让关键帧在一整场戏里保持住的人物与场景一致性方法论。

两个文件描述的都是能力类别，不是实时功能清单。厂商改参数极频繁，落地前请以官方最新文档为准。

输出模式

模式可组合。完整制作流程通常是 A→B→C→D→E→F→H→I，G 在底下贯穿，J 收尾。

扩展方式

• 加导演：新建 references/director_styles/NN_<slug>.md，沿用 v2 结构，填满 风格参数，使用统一对照场景，然后在 4 处登记。
• 加视频/图像工具：追加一段适配器加一列能力矩阵。除非该工具改变了全局默认值，否则不用动 SKILL.md。
• 加类型片：在 references/genre-playbooks.md 追加一块，字段集与现有类型一致，并在对比表加一行。
• 加失败代码：F 编码只增不改，从 F19 起，四个区块齐全。
• 加输出模式：只有真正区别于 A–J 时才加。
• 加 eval：在 evals/evals.json 追加用例。

完整贡献指南见 CONTRIBUTING.md。

使用规则与免责声明

导演风格模块描述的是高层方法——叙事倾向、镜头语法、灯光逻辑、剪辑节奏、声音、表演、可迁移清单。它们不授权复制任何导演真实电影中的具体镜头、台词、角色、剧情或其他受版权保护的表达。请把它们当作镜头来启发原创作品。

工具适配器描述的是写作当时观察到的能力类别。AI 视频与图像平台的限制、参数、功能变动频繁，落地前请以厂商最新文档为准。

许可证

MIT，见 LICENSE。

MIT 授权覆盖 skill 文件本身。上方"使用规则"约束的是如何把这些导演知识应用到已有电影上，是与软件许可分开的另一个问题。