hyperframes-student-kit Agent技能架构：.claude/skills与Codex .agents镜像如何同步协作（完整指南）

hyperframes-student-kit 是一个用 Codex 或 Claude Code 剪辑视频、Reels 和 YouTube Shorts 的 AI 视频剪辑套件，包含 15 个 Agent 技能、406 张动效卡片和 HyperFrames 模板。它的 Agent 技能架构采用"单一事实源 + 自动生成镜像"的设计：规范技能存放在 .claude/skills/ 目录，再由 scripts/sync-codex-skills.mjs 脚本一键同步为 Codex 可发现的 .agents/skills/ 镜像。理解这套同步协作机制，是你自定义或扩展技能的前提。


双目录结构：谁才是"规范源"

项目根目录下有两份内容几乎相同的技能目录，但职责完全不同：

两个 Agent 运行时读取的工作区指南也是"一对"：AGENTS.md 供 Codex 读取，CLAUDE.md 供 Claude Code 读取。仓库要求两者内容保持一致（当前两者逐字节相同），其中明确写道："Claude Code uses.claude/skills/. Codex uses the generated.agents/skills/."

这套设计的核心原则只有一条：只改.claude/skills/，然后运行同步。

技能包解剖：一个 SKILL.md 如何组织

每个技能是一个独立文件夹，以SKILL.md为核心。以完整的视频剪辑技能 edit-video/SKILL.md 为例，其结构如下：

.claude/skills/edit-video/ └── SKILL.md # YAML frontmatter + 工作流程指令

较大的技能还会携带三类辅助资源：

• scripts/：可执行的 Node 辅助脚本，例如cut-silences技能内嵌的剪辑脚本；
• references/：按需加载的参考文档，避免主文件过长；
• NOTICE.txt：第三方来源声明（来自外部仓库的技能会附带）。

SKILL.md开头的 YAML frontmatter 是路由关键——name和description会被 Agent 用来判断"什么时候该加载这个技能"，正文才是具体执行步骤。例如edit-video的描述就是"对原始口播视频做转写、静音修剪、口误审查、视觉叙事与渲染验证的完整剪辑流程"。

全部 15 个技能的职责路由表收录在 AGENTS.md 中，新手可以对照这张表快速找到对应技能：short-form-edit（Reels/Shorts）、edit-video（完整剪辑）、cut-silences（静音切除）、cut-mistakes（口误/重录）、video-storytelling（叙事弧线）、style-library（风格与卡片库）、gsap（时间线动画）、hyperframes-cli（预览/lint/渲染）等。

一键镜像同步：sync-codex-skills 脚本的核心逻辑

整个架构最关键的一环只有约 40 行代码，全部在 scripts/sync-codex-skills.mjs 中。它的工作分三步：

1. 递归遍历规范源

从.claude/skills/深度优先遍历所有文件，自动跳过node_modules、__pycache__、.DS_Store等噪声，当前共 106 个技能文件被纳入同步。

2. 复制时做"路径感知"改写

脚本对每类文件采取不同策略：

• .md指令文件：把内容中的.claude/skills/统一改写为.agents/skills/。因为技能正文里包含运行时命令（如node .claude/skills/cut-silences/scripts/cut-silences.mjs ...），Codex 侧执行时路径必须指向镜像目录；
• 脚本、数据等资源文件：逐字节原样复制，保持完全一致。

3. 反向检查"多余镜像"

同步完成后，脚本还会遍历目标目录，报告任何在源中不存在的"Extra mirror file"，防止历史残留文件干扰 Agent 行为。

两条 npm 命令完成日常协作

package.json 中注册了两个脚本：

npm run sync:skills # 全量同步 .claude/skills -> .agents/skills npm run check:skills # 只检查不同步；发现差异或多余文件时以退出码 1 结束

--check模式可直接接入 CI：只要有人手改了镜像目录或漏跑同步，检查就会失败。

💡为什么不用符号链接？注释写得很清楚："The mirror uses real files so Windows users do not need symlink privileges."——镜像是真实文件，Windows 用户无需额外权限即可使用。

skills-lock.json：外部技能的"版本锁"

15 个技能中，有 5 个（gsap、hyperframes、hyperframes-cli、hyperframes-registry、website-to-hyperframes）并非原创，而是从 heygen-com/hyperframes 上游仓库引入的。skills-lock.json 对每个引入技能记录了source、sourceType和一个computedHash（SHA-256 摘要）：

{ "gsap": { "source": "heygen-com/hyperframes", "sourceType": "github", "computedHash": "bf85f05f3c0146c18d6f6ff23e6a4cd4a7853462a6d637ea389b610f584d55f8" } }

这相当于给外部技能上了"版本锁"：内容一旦变化，哈希即可用于校验与追溯，与仓库中 THIRD_PARTY_NOTICES.md 的来源声明配套。

调用技能：Codex 的$与 Claude Code 的/

镜像存在的意义就是让两个 Agent 都能"自动发现"技能：

• Codex：打开项目后自动发现.agents/skills/下的全部技能包，用$edit-video、$cut-silences调用，或直接自然语言描述；.codex/README.md 说明了这一发现机制；
• Claude Code：直接读取规范目录.claude/skills/，用/edit-video、/short-form-edit调用。

一个常见坑：新增技能后 Codex 里看不到？按 docs/SETUP.md 的建议，确认信任了项目设置并重启 Codex即可；另外.codex/config.toml只设置了文档加载上限（project_doc_max_bytes = 65536）和回退文件名，刻意不触碰用户的模型、鉴权与沙箱配置。

上图为技能链路实际产出的项目画面之一（video-projects/linear-promo-30s/）：从脚本驱动截屏、构图合成到最终渲染，全程由技能指令编排完成。

技能维护最佳实践：更新三步走

修改任何技能只需记住标准三步（来自 docs/SETUP.md）：

1. 编辑规范源：只改.claude/skills/<name>/下的文件；
2. 执行同步：npm run sync:skills；
3. 验证镜像：npm run check:skills，确认 0 差异。

再补两条守则：

• 修改工作区指南时，同步更新 AGENTS.md 与 CLAUDE.md，保持逐字一致；
• 删除技能后跑一次--check，清理.agents/skills/中被报告为多余的镜像文件。

总结

hyperframes-student-kit 的 Agent 技能架构可以用一句话概括：.claude/skills/是唯一的写作台，.agents/skills/是自动印刷的分发版，sync-codex-skills.mjs是印刷机，skills-lock.json是版权登记簿。这套"规范源 + 路径感知镜像 + 哈希锁"的组合，让同一套 15 个视频剪辑技能在 Claude Code 与 Codex 中行为一致，也为后续自行编写新技能提供了清晰的扩展路径。