claude-video的SKILL.md契约设计：一份文档如何让AI看视频技能共用三个平台
claude-video的SKILL.md契约设计一份文档如何让AI看视频技能共用三个平台【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-videoclaude-video是一个让 Claude 获得看视频能力的开源项目输入一个视频链接或本地路径它会下载视频、抽取帧、生成带时间戳的字幕/转录文本然后把画面和文稿一起交给 Claude 回答你的问题。这个项目最巧妙的设计在于整条AI 看视频流水线只由一份 SKILL.md 文档来定义却被 Claude Code、claude.ai 网页版、Codex 三个平台共同加载——它就是所谓的契约设计。本文带你拆解这份契约为什么能一鱼三吃。什么是 SKILL.md 契约头部给机器正文给 AI打开 SKILL.md你会发现它由两部分组成各司其职① YAML 头部frontmatter——给平台看的机器元数据。见 SKILL.mdname: watch、description、argument-hint—— 告诉平台这个技能叫什么、干什么、参数长什么样allowed-tools: Bash, Read, AskUserQuestion—— 声明技能允许使用的工具权限边界写在明处homepage、repository、author、license、user-invocable: true—— 标准的署名与可见性声明② Markdown 正文——写给 AI 的操作说明书。这不是给人读的博客而是一份可执行的流程契约AI 会严格照做章节作用Step 0 预检每次调用前先静默检查依赖和 API Key失败按退出码查表处理When to use / Recommended limits告诉 AI 何时触发技能、视频多长最准10 分钟内How to invokeStep 1–5解析输入 → 跑watch.py→ 读帧图 → 作答 → 清理Failure modes下载失败、无字幕、Whisper 报错时分别怎么办Token efficiency80 帧约 50–80k 图像 token教 AI 省着用Security Permissions明确做什么和绝不做什么不上传视频本身、不碰账号关键点是正文里没有一行平台专属的假设。脚本路径一律用环境变量${CLAUDE_SKILL_DIR}/scripts/...引用而不是写死绝对路径于是同一份文字在任何平台上指的都是同一批脚本。一份文档三个平台各自读什么README 里的结构注释一句话点题SKILL.md # skill contract — loaded by all three surfaces。三个平台的差异全部被隔离在打包层契约本身纹丝不动Claude Code插件 斜杠命令 启动钩子通过 .claude-plugin/plugin.json 和 marketplace.json 注册为市场插件用户执行/plugin install watchclaude-video即可commands/watch.md 是一个 9 行的垫片把/watch这个斜杠命令桥接到 SKILL.md 定义的完整流水线——没有它插件装上了但命令不可用见 CHANGELOG.md 0.1.1 修复记录hooks/hooks.json 配置 SessionStart 钩子在会话启动时跑 check-setup.sh配置齐全就保持安静缺东西才打一行提示claude.ai 网页版打包成 .skill 上传claude.ai 不认 git 仓库只认一个技能包。项目用scripts/build-skill.sh把仓库打包成dist/watch.skill打包时会剥掉commands/、hooks/、.claude-plugin/这些 Claude Code 专属目录——契约文档和 Python 脚本原样保留。.github/workflows/release.yml 在打 tag 时自动构建并附上发布用户下载后在 Settings → Capabilities → Skills 拖进去即可。Codex整仓克隆通用技能目录Codex 走最简单的路把整个仓库克隆到技能目录即可SKILL.md作为通用技能被识别git clone https://gitcode.com/GitHub_Trending/cl/claude-video.git ~/.codex/skills/watch.codex-plugin/plugin.json 只有 22 字节就一个name字段因为 Codex 需要声明的本来就少。一句话总结契约稳定打包可变平台加载方式平台专属文件SKILL.mdClaude Code插件市场安装commands/、hooks/、.claude-plugin/原样加载claude.ai上传watch.skill包打包脚本剥离专属目录原样加载Codexgit clone到技能目录.codex-plugin/原样加载这种契约设计对开发者意味着什么1. 单一事实来源消灭多份文档漂移。三个平台如果各写一份说明改一处漏两处是迟早的事。claude-video 把流程只写一遍任何修复比如 0.1.2 中给 Windows 补充python而非python3的说明都只需改 SKILL.md 一行三个平台同步生效。2. 元数据与行为分离。头部 frontmatter 回答这个技能是什么注册、命名、权限正文回答这个技能怎么跑流水线、边界、失败处理。平台各取所需互不干扰。3. 把平台差异推到最外层。差异只存在于三处命令垫片commands/watch.md、启动钩子hooks/、打包脚本build-skill.sh。核心契约用环境变量引用资源天然跨平台。4. 契约即安全声明。正文的 Security Permissions 一节明确列出技能做什么、绝不做什么不上传视频本身、不触碰平台账号、密钥不混用、0600 权限。对新手来说安装任何 AI 技能前读这节比读代码更快建立信任。上手体验装好就能用Claude Code/plugin marketplace add/plugin install watchclaude-videoclaude.ai下载最新的watch.skill释放文件拖入技能设置Codex执行上文的一行 clone 命令零配置启动首次/watch调用时SKILL.md里的 Step 0 会让 scripts/setup.py 静默预检——macOS 自动brew install ffmpeg yt-dlpLinux/Windows 打印精确安装命令并在~/.config/watch/.env里生成密钥占位文件。之后每次调用只花不到 100ms 的检查完全无感。试试这条命令感受一下/watch https://youtu.be/xxxxx 第30秒发生了什么Claude 会下载视频、抽取自动缩放帧率的画面、对齐字幕时间戳然后像一个真正看过视频的人那样回答你。而背后支撑这一切的就是那份同时服务三个平台的 SKILL.md——契约式设计的好例子往往不是写得更复杂而是写得更克制。【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考