用途 video-transcripts 用于为本地视频文件或视频 URL 生成结构化视频转写文本。典型使用场景是：GitHub 或 Linear 的 issue、PR、评论或附件中包含屏幕录制，需要获得带时间轴的转写内容，而不是模糊摘要。
主要能力 该技能通过脚本 .agents/skills/video-transcripts/scripts/generate_video_transcript.sh 运行，每次针对一个相关视频执行。它支持本地文件路径和远程 URL 两类输入。对 Linear 上传（uploads.linear.app）的鉴权视频，在 macOS 上会自动使用本地 Linear 桌面应用的 cookie 重试；对私有 GitHub 资源 URL，会依次尝试 GITHUB_TOKEN、GH_TOKEN、gh auth token，最后回退到未鉴权下载。调用 Gemini 时会查找 GEMINI_API_KEY，其次 GOOGLE_API_KEY，若都未设置则尝试 ~/.bash_profile。
使用方式 脚本基本调用形式如下：
bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh "https://uploads.linear.app/.../screen-recording.mov" --title "PDF preview hyperlinks trigger leave-page modal"
也可传入 GitHub 附件 URL 或本地文件绝对路径。每次运行应给出简短、聚焦 bug 的 --title。
输出约定为 XML，而非 Markdown。每个观察到的动作或系统响应占一行，格式为 [MM:SS] (...)。可辨认时引用可见的 UI 文本；只描述可见动作、屏幕变化以及存在时的可听语音；不得臆造隐藏状态、动机或实现细节。优先使用简洁、高信号的表述。
对于被跟踪的工作，规范共享缓存应放在 tracker 中、紧邻其所描述的凭证：若视频在 issue 或 PR 正文中，使用顶层 tracker 评论；若视频在 Linear 评论中，将转写缓存作为对该评论的回复；若视频在 GitHub issue 或 PR 评论中，为该来源评论的视频集使用一条专用的顶层缓存评论（GitHub 无回复，因此按来源容器分隔缓存评论）。缓存评论或回复正文应仅为 XML。source-key 是媒体的规范化稳定标识；对 uploads.linear.app 这类带签名的 URL，应去掉查询字符串。缓存正文保持纯 XML，不添加标记、说明文字或 YAML。重新转写前先按来源容器匹配缓存条目。不要将原始 tracker 转写缓存放入 docs/。
模型策略 默认使用 gemini-3.1-flash-lite-preview 以控制成本；若输出格式错误、内容过薄或明显嘈杂，则自动回退到 gemini-3-flash-preview。对 Gemini 3 模型，强制最小思考，使输出预算用于转写而非隐藏推理。可通过环境变量覆盖，例如 VIDEO_TRANSCRIPTS_MODEL=gemini-3-flash-preview，也可通过 --model 参数指定，例如 --model gemini-2.5-flash。
适用场景与限制 适用于需要时间轴式转写行、并希望结果符合指定 XML 形状的场景。质量门会拒绝明显低信号的转写（如重复的部分输入片段）并自动回退。使用 --debug-dir <dir> 可保存请求与响应产物。若通过 codex exec 调用，建议使用 -o <file> 以捕获最终 XML，避免 CLI 进度信息干扰。收费、价格等信息暂未提供。