Communitygithub.com

故事板架构师

将视频简报转化为包含镜头规格、时间线、屏幕文字及每镜头理由说明的故事板和镜头列表。当用户请求故事板、镜头列表、逐节节拍或视频的结构化前期制作,或提交脚本/概念要求分解为镜头时使用。生成 run.json、storyboard.md、shots.json、text-overlays.json 和 brand-lock.snapshot.md。负责规划视频,不执行渲染。

故事板架构师 是什么?

**故事板架构师** 是一款专为 AI 编程代理(如 Claude Code、Cursor、Codex 等)设计的高级技能,旨在将创意视频简报转化为精确、可执行的故事板与镜头列表。其核心价值在于将模糊的“讲故事”需求转化为工程师、剪辑师或广告代理商可直接操作的确定性规范文件,杜绝后续沟通中的歧义。该技能支持多个主流 AI 代理平台,通过严格的文件结构和内容哈希审计追踪,确保每个项目的可追溯性。它要求输入如时长、宽高比等关键参数,并可选择品牌锁定文件以保持视觉一致性。工作流程涵盖读取品牌锁定、选择节拍框架(如痛苦-重塑-承诺三部曲)、按规则分段时间、按可控词汇编写镜头列表、分离屏幕文字层、锁定系列环境与角色、为每个镜头撰写一句话理由,最后生成包含所有输入内容哈希的 `run.json` 作为完整审计轨迹。该技能不生成图像或预览,但可无缝对接配套技能 `visual-prompt-forge`(生成图像提示)和 `storyboard-html-preview`(生成 HTML 预览)。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dheerazsah/video-editor-skills/tree/HEAD/skills/storyboard-architect

在你喜欢的 AI 中提问

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

文档

故事板架构师 是做什么的?

你正在将一个创意简报转化为一个确定性的故事板。输出是一组文件,供剪辑师、广告公司或开发者直接使用,无需追问后续问题。

这不是一次创意写作练习。输出是一份规范说明。

何时使用

当用户出现以下情况时,触发此技能:

  • 请求为视频创建故事板或镜头列表(例如:“为一个 30 秒的产品说明故事板……”、“为一个 TikTok 广告编写镜头列表……”)
  • 要求规划镜头、分解节拍,或编写镜头列表
  • 提交脚本、简报或概念文档,期望得到结构化的前期制作输出
  • 按名称提及节拍框架(英雄三部曲、痛苦-证明-承诺等)
  • 引用现有的品牌锁定文件或包

如果用户只需要图像生成器的提示(无需叙事结构),请直接使用 visual-prompt-forge。

你将生成什么

对于每次故事板运行,在工作输出目录中创建以下确切的一组文件:

output/
├── run.json                   # 运行身份 + 每个输入的内容哈希
├── storyboard.md              # 人类可读的、按镜头组织的结构
├── shots.json                 # 机器可读的,模式位于 templates/shots.schema.json
├── text-overlays.json         # 屏幕文字 + 时间
└── brand-lock.snapshot.md     # 所使用的品牌锁定的冻结副本(审计轨迹)

run.json 是让其余文件树事后可审计的关键。文件名本身无法说明其背后的字节内容,因此与一组帧并列的快照并不能证明它就是构建这些帧的原始快照。run.json 中的哈希就是这种证明。在其他四个文件最终确定后,最后一步一次性写入 run.json。run.json 中除 rounds 之外的所有内容仅写入一次,永不编辑。rounds 是仅追加的:visual-prompt-forge 为每轮提示添加一个条目,并且从不更改先前的条目。

如果用户要求图像提示或 HTML 预览,请将任务移交给 visual-prompt-forge 或 storyboard-html-preview,这些技能直接消费 shots.json。不要在这里尝试做它们的工作。

工具和包的存放位置

在运行 ./install.sh 之后,验证器和帮助程序位于 ~/.claude/shotkit-tools/,品牌包位于 ~/.claude/shotkit-brand-packs/。--project 安装会将两者都放在 ./.claude/ 下。从仓库克隆中,它们分别是 tools/ 和 brand-packs/。下面的命令首先给出安装路径,然后给出克隆路径。它们无需设置:sk 运行每个工具并提供验证器使用的两个 Python 包。

输入

你需要这些输入。如果缺少任何一项,请在起草前询问。

输入必需?缺失时的默认值
简报(问题、受众、目标)是询问
总时长是询问
宽高比是询问(16:9, 9:16, 1:1)
节拍框架否根据简报建议
品牌锁定文件路径否使用 ~/.claude/shotkit-brand-packs/_starter.md(克隆:brand-packs/_starter.md)并标记缺口
画外音风格(存在 VO、仅屏幕文字、字幕)否如果不明确则询问
下游提示的目标生成器否注明为“待指定”
审计结果,来自 whystrohm-audit 的 brand/audit-findings.json否跳过步骤 1b

阅读预算

此文件包含正常运行所需的内容:字段、词汇和文件结构。不要一次性阅读所有参考资料、模板和示例。那会浪费用户数分钟时间才能开始写入第一个文件。

  • 始终阅读:品牌锁定。
  • 当决策需要时阅读:references/beat-frameworks.md(用于你不熟悉的框架)、references/timing-rules.md(当简报和时长不一致时)、references/on-screen-text.md(当你不确定某行文字是否应上屏时)。
  • 当验证器提示时阅读:templates/ 中的模式。它的消息会指出字段和规则,因此首先从消息修复。
  • 最后阅读(如果确实需要):示例。

工作流程

遵循此顺序。即使简报看似简单,也不要跳过任何步骤。

步骤 1. 读取品牌锁定

如果提供了品牌锁定文件路径,请先读取它。提取:

  • 调色板(十六进制)
  • 字体排印学
  • 情绪描述词
  • “永不”列表(该品牌绝不会在视觉上表现的内容)
  • 动态语言
  • 语音语调
  • 宽高比偏好

如果未提供品牌锁定,请将 ~/.claude/shotkit-brand-packs/_starter.md(从克隆中,为 brand-packs/_starter.md)复制到输出目录,命名为 brand-lock.snapshot.md。该启动模板是中性的、已填充的锁定,因此快照能通过其检查,并且覆盖层能有可用的真实颜色。在 run.json 中设置 brand_lock_configured: false,并告知用户本次运行使用了启动品牌,以及如何替换它:要求用户提供其网站的品牌锁定,或填写 _template.md。

不要对 _template.md 进行快照。它故意是空白的,空白调色板会导致快照检查失败。也不要为真实公司编造调色板:编造的品牌锁定看起来像是公司做的决定,但实际上并非如此。

步骤 1b. 读取审计结果(如果有)

如果用户指向 brand/audit-findings.json,或者它位于项目的 brand/ 文件夹中且简报是针对同一家公司,请读取它。其格式为此仓库中的 contracts/audit-findings.v1.schema.json。在使用前,检查 contract 是否为 audit-findings,version 是否为 "1"。

  • top_gaps 中的第一个条目是痛苦或世界节拍的候选:即影片要解决的问题。
  • rewrite.after 是候选覆盖行。仅按原样使用。如果其中包含括号内的占位符,则表示缺少证据,因此请省略该行而不是填充它。
  • 在 storyboard.md 的简报部分命名该文件及其 audited_at。

简报仍然起决定作用。审计结果提供信息;它们永远不会取代用户的要求。

步骤 2. 选择节拍框架

阅读 references/beat-frameworks.md。选择与简报匹配的一个。常见情况:

  • 痛苦-重塑-承诺 → 转化内容
  • 英雄三部曲 → 产品英雄影片
  • 创始人讲解 → 个人品牌内容
  • 内容螺旋 → 动态文字 / 观点文章

如果没有合适的选择,构建自定义节拍结构,但在 storyboard.md 的说明部分记录原因。

步骤 3. 划分时间块

阅读 references/timing-rules.md 了解计算方法。默认节奏:

  • 钩子节拍:0–2 秒
  • 痛苦/设置:2–4 秒(15 秒视频)、2–6 秒(30 秒视频)或 2–10 秒(60 秒视频)
  • 证明/重塑:中间三分之一
  • 承诺/CTA:最后 3–4 秒(15 秒视频)、4–6 秒(30 秒视频)、6–10 秒(60 秒视频)

不要与框架对抗。如果简报和时长不一致,请在起草前指出该不一致。

步骤 4. 起草镜头列表

阅读 references/shot-grammar.md 了解受控词汇。下面的字段名称是模式的字段名称。templates/shots.schema.json 设置了 additionalProperties: false,因此像 environment 而非 environment_ref 这样的近似命中是验证失败,而不是同义词。

  • id,顺序,零填充(shot_01, shot_02...)
  • beat,此镜头服务的节拍
  • start / end,以秒为单位的时间戳,允许小数。end 必须在 start 之后
  • framing,ECU / CU / MCU / MS / MLS / WS / EWS
  • angle,eye-level / high / low / overhead / dutch
  • motion,static / push / pull / pan-left / pan-right / tilt-up / tilt-down / handheld / orbit / whip / rack。所有十一个都是合法的;模式枚举是权威,references/shot-grammar.md 解释了每种方式在何时发挥作用
  • depth_of_field,可选,shallow / deep / rack
  • subject,画面中的主体,结构化描述
  • environment_ref,引用系列锁定语言,默认 series_lock.environment
  • lighting_ref,引用系列锁定语言,默认 series_lock.lighting
  • on_screen_text,null,一个文字覆盖层 ID,或者当一个镜头有多个覆盖层时的 ID 数组
  • vo,画外音台词,或 null
  • rationale,一句话解释为什么此时有这个镜头

关于 rack 的说明:作为 motion 值,它意味着聚焦转换是镜头的运动;作为 depth_of_field 值,它意味着焦点在镜头中途发生转移。同一单词,两个字段,两种含义。

步骤 5. 分离文本层

每一段屏幕上显示的文字都成为 text-overlays.json 中的一个条目。切勿将文本嵌入到视觉描述中。每个覆盖层具有:

  • id,text_01, text_02...
  • shot_id,此覆盖层所处的镜头
  • content,实际文本
  • font,引用品牌锁定字体排印学
  • position,center, lower-third, upper-third, left-third, right-third,或 {x, y} 百分比
  • size,display, headline, body, caption
  • weight,regular (400), medium (500), semibold (600), bold (700), black (900)
  • color,十六进制(必须来自品牌锁定调色板)
  • enter,{ at: seconds, animation: fade-in | slide-up | slide-down | type-on | hard-cut }
  • exit,{ at: seconds, animation: fade-out | slide-up | slide-down | hard-cut }

然后设置文字类型并检查措辞:

  • 文字类型处理。 用 emphasis 标记承载每个标题的两三个单词,用 kicker 或 lockup 命名品牌一次,在画面繁忙时使用 plate。字段以及何时使用每个字段的信息在 references/on-screen-text.md 的“文字类型处理”部分。
  • 语言检查。 在写入文件之前,将每一行文字通过 references/hooks-and-language.md 进行检查:第一行应该是钩子而非口号,使用具体的词语,每行一个想法,不要包含简报未提供的信息。
  • 没有字体的品牌。 从品牌包文件夹的 type-pairings.md 中选择一对字体组合,并将其写入品牌锁定。不要默认使用 Inter 字体。

Enter 和 exit 具有不同的动画词汇表,templates/text-overlays.schema.json 是两者权威。一个镜头可能带有多个覆盖层;在镜头的 on_screen_text 数组中列出每个 ID,否则额外的覆盖层将无法渲染。

步骤 6. 锁定系列

定义适用于所有镜头的环境、灯光和角色锚点。这些内容放在 shots.json 顶部 series_lock 下。没有这些,图像生成将产生不连贯的帧。

步骤 7. 编写理由

每个镜头都有一句话理由。为什么是这个节拍。为什么是这个取景。为什么是这段屏幕文字。这是审计轨迹。不要跳过。

步骤 8. 快照品牌锁定

将品牌锁定文件(或模板)复制到输出目录,命名为 brand-lock.snapshot.md。在文件最顶部按顺序添加以下两个注释:

<!-- snapshot taken: 2026-05-07T14:23:00Z -->
<!-- source: brand-packs/whystrohm.md -->

时间戳是一个完整的 UTC 时刻,YYYY-MM-DDThh:mm:ssZ。仅写日期无法区分同一天内的两次运行,而这是最关键的情况。路径是它被复制来源的路径,对于未配置的运行,则为字面字符串 template default。安装后,包路径为 ~/.claude/shotkit-brand-packs/whystrohm.md;从仓库克隆中,则为 brand-packs/whystrohm.md。两者都能通过验证器。在这两个注释之后添加额外注释是可以的。

validate_brand_lock.py --snapshot <path> 检查这两行。运行它:

~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# from a repo clone:
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md

步骤 9. 编写 run.json

最后一步,在其他四个文件最终确定后。填写 templates/run.schema.json。以下字段是必需的:

字段值
version"1.0",run.json 格式版本
run_id紧凑 UTC 时间戳,一个短横线,8 个十六进制字符(见下文)
created_at与 YYYY-MM-DDThh:mm:ssZ 相同的时刻
shotkit_version~/.claude/shotkit-tools/VERSION 的第一行;在仓库克隆中,为根目录下的 VERSION
projectshots.json 中的 title、duration_s 和 aspect,以及 framework 和 seed(如果已设置)
inputs.shots_ref、inputs.shots_sha256shots.json 及其 SHA-256
inputs.text_overlays_ref、inputs.text_overlays_sha256text-overlays.json 及其 SHA-256,如果没有屏幕文字则两者均为 null
inputs.brand_lock_ref、inputs.brand_lock_sha256brand-lock.snapshot.md 及其 SHA-256
inputs.brand_lock_source复制来源的包,或 template default

可选:operator、inputs.brand_lock_configured、generators、rounds、meta。

head -n 1 ~/.claude/shotkit-tools/VERSION     # from a repo clone: head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md

run_id 是紧凑 UTC 时间戳,一个短横线,然后 8 个十六进制字符,例如 20260730T142300Z-9f2c1ab4。十六进制后缀用于防止两个操作员在同一秒开始运行时发生冲突。当快照是未填充的模板时,设置 brand_lock_configured: false。

将 rounds 留空。run.json 中除 rounds 之外的所有内容仅写入一次,永不编辑。rounds 是仅追加的:visual-prompt-forge 为每轮提示添加一个条目,并且从不更改先前的条目。

输出格式

storyboard.md

每个段落一个标题,按此顺序:给定的简报、你做的假设、框架及原因、系列锁定,然后每个镜头一个块(ID、节拍、时间、相机、主体、屏幕文字、VO、理由),最后如果有的话,提供完整 VO 脚本。templates/storyboard.md.tpl 有确切的布局(如果你想要的话)。

shots.json

必须通过 templates/shots.schema.json 的验证。结构如下:

{
  "version": "1.2",
  "project": { "title": "...", "duration_s": 30, "aspect": "9:16", "framework": "..." },
  "brand_lock_ref": "brand-lock.snapshot.md",
  "series_lock": {
    "character": "...",
    "environment": "...",
    "lighting": "...",
    "color_grade": "..."
  },
  "shots": [
    {
      "id": "shot_01",
      "beat": "hook",
      "start": 0.0,
      "end": 2.0,
      "framing": "MCU",
      "angle": "eye-level",
      "motion": "static",
      "depth_of_field": "shallow",
      "subject": "手部特写,正在打开一个无标识的盒子",
      "environment_ref": "series_lock.environment",
      "lighting_ref": "series_lock.lighting",
      "on_screen_text": "text_01",
      "vo": null,
      "rationale": "开场钩子:好奇心驱动观众继续观看,MCU 景别让盒子填满画面并暗示其重量。"
    }
  ]
}

text-overlays.json

必须通过 templates/text-overlays.schema.json 的验证。

{
  "version": "1.0",
  "overlays": [
    {
      "id": "text_01",
      "shot_id": "shot_01",
      "content": "改变从这里开始",
      "font": "Gilroy-Bold",
      "type": "headline",
      "treatment": "emphasis",
      "position": "center",
      "size": "headline",
      "weight": "bold",
      "color": "#1E3A8A",
      "enter": { "at": 0.5, "animation": "fade-in" },
      "exit": { "at": 1.8, "animation": "fade-out" }
    }
  ]
}

run.json 模式(摘要)

参见 templates/run.schema.json。这是包含哈希的根审计文档。

验证

在所有主要步骤之后运行验证器。每个验证器遵循 sk <validator> <args> 模式。安装后:

~/.claude/shotkit-tools/sk validate_shots.py output/shots.json
~/.claude/shotkit-tools/sk validate_text_overlays.py output/text-overlays.json
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md

从仓库克隆:

tools/sk validate_shots.py output/shots.json
tools/sk validate_text_overlays.py output/text-overlays.json
tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md

如果验证器报错

  1. 读取错误消息。它提到字段和问题。
  2. 读取相关的模式(templates/shots.schema.json 等)以理解确切约束。
  3. 修复文件。不要忽略验证器。
  4. 重新运行验证器。

不进行验证就继续会导致下游工具崩溃,从而浪费用户时间。

用法示例

(本示例已针对翻译进行了简化;更详细的示例在仓库的 examples/ 目录中。)

用户:“为我的 SaaS 产品创建一个 30 秒的 TikTok 广告的故事板。目标观众是 25-40 岁的小企业主。简报:他们花太多时间手动处理发票。”

系统:

  1. 阅读品牌锁定(如果提供了;否则使用启动模板)。提取调色板(例如,蓝色 #0F172A,白色 #F8FAFC),字体(Inter),情绪(专业、现代)。
  2. 选择框架: 痛苦-证明-承诺(Pain-Proof-Promise)。
  3. 划分时间块:
    • 钩子:0-2 秒
    • 痛苦:2-6 秒
    • 证明:6-24 秒
    • 承诺:24-28 秒
    • CTA:28-30 秒
  4. 起草镜头列表(shots.json):8 个镜头,详细说明取景、角度、运动。每个镜头一句话理由。
  5. 分离文本层(text-overlays.json):4 个覆盖层,与镜头匹配。
  6. 锁定系列。
  7. 快照品牌锁定。
  8. 编写 run.json(最后一个文件)。

输出: output/storyboard.md、output/shots.json、output/text-overlays.json、output/run.json、output/brand-lock.snapshot.md。

相关技能

  • visual-prompt-forge:消费 shots.json,为图像生成器生成提示。
  • visual-asset-critic:审查生成的资产。
  • storyboard-html-preview:从 shots.json 构建 HTML 故事板预览。

这些技能直接使用此技能的输出文件(shots.json),形成模块化工作流。

Individual skills in this repo

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

相关技能