Skill Anatomy

h3-prompt-writing
设计结构拆解

一个把多模态需求重写为 MiniMax H3 视频生成提示词的 Agent Skill。 核心设计：轻入口 + 按需加载指南 + 严格格式契约，不依赖任何外部 API，可移植到任意能读本地文件的 Agent。

01文件结构 —— 总共只有 4 个文件

h3-prompt-writing/
├─ SKILL.md41 行 · 入口← Agent 第一眼读的：元信息 + 工作流路由 + 输出规则，绝不堆细节
├─ references/
│  ├─ base-en.txt222 行← 基础模式指南（T2VA / I2VA / FL2VA / L2VA），用到才读
│  └─ ref-en.txt341 行← 全参考模式指南（Ref2VA），用到才读
└─ agents/
    └─ openai.yaml4 行← 可选的 ChatGPT/Codex UI 元数据（显示名/短描述/默认 prompt）
设计精髓：渐进式上下文加载。SKILL.md 只做"路由器"——先判断输入模式，再指向具体 reference 文件。Agent 不用一次性吞下 500+ 行指南，省 token 又不容易走神。

02核心工作流 —— 四步路由

STEP 1
识别输入模式
判定是 T2VA / I2VA / FL2VA / L2VA 还是全参考 Ref2VA
STEP 2
选指南文件
基础模式 → base-en.txt；全参考 → ref-en.txt
STEP 3
按结构重写
严格跟随指南的最终 prompt 结构与段落顺序
STEP 4
格式契约校验
字段名、段落顺序、标签、时间记法逐项保持原样

03五种输入模式

T2VA纯文本

从文字构建完整视听时间线，无首帧对齐指令

I2VA首帧

从首帧出发向后发展：锚定 → 起势 → 连续演化 → 结果

FL2VA首尾帧

描述首帧到尾帧之间的连续路径与状态演化

L2VA尾帧

推断合理开头，向给定的尾帧收敛

Ref2VA全参考

多素材（图/视频/音频）整体重写，六段式输出

04输出结构 —— base 三字段 vs ref 六段式

基础模式（base-en.txt）

首行是对齐指令（I2VA/FL2VA/L2VA 各有固定句式），随后三个核心字段：

1integrated_multimodal_description画面·动作·镜头·台词·画内音
2overall_soundscape环境音·动作声·非语言人声
3non_diegetic_music只有观众能听到的配乐
全参考模式（ref-en.txt）

六段固定顺序，标签一旦定义全文一致：

1subject_definitions定义参考素材与标签
2summary任务类型与参考关系概述
3retention_analysis保留/迁移/复用分析
4detailed_description按播放顺序逐镜头描写
5overall_soundscape环境与动作声音
6non_diegetic_music画外配乐

05参考标签体系（Ref2VA）

标签含义典型用途
<Subject N>从参考素材中抽象出的可复用/可修改内容人物、环境、结构等"角色"级定义
<Picture N>作为具体目标帧或分镜锚点的参考图关键帧对齐（I2VA/FL2VA/L2VA）
<Video N>提供剪辑源、续接起点或全片时间结构的参考视频续接生成、节奏复刻
<Audio N>被复制或引用的音频信号配音/歌曲迁移
标签的生命周期规则：一旦分配，在全部六段中保持同一含义——这是它防止 Agent 写着写着把 <Picture 1> 和 <Picture 2> 搞混的核心约束。

06输出纪律（SKILL.md 里写死的红线）

07设计评价 —— 值得抄的四件事

① 路由器式入口

SKILL.md 只做模式判定和文件分发，41 行讲完。你的 skill 里正文越长，Agent 遵循率越低——细节外包给 references 是对的。

② 格式即契约

字段名、顺序、标签、时间记法全部"必须原样保留"。生成类任务的稳定性靠的是把自由度压到最低。

③ 固定句式模板

I2VA/FL2VA/L2VA 的对齐指令直接给完整模板句，Agent 填槽即可，不留给它发挥"文采"的空间。

④ 兼容性声明

frontmatter 里明确"可移植到任何 Agent"，agents/openai.yaml 只做可选增强——一份 skill 同时服务 Claude Code 和 Codex。