mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-04 16:42:27 +00:00
James RussoandJake Moran
e96ebd74de
Packages Jake Moran's changelog-video pipeline (v1, validated end-to-end
by Home on the Jun 23-29 range) as a repo-native skill set that Claude
Code (.claude/skills/) and Codex CLI (.agents/skills/) auto-discover the
moment the repo is opened. No install step; run the skill against a
changelog markdown for a given git range and it produces a lint-clean,
seam-gate-green 1080x1080 MP4 (~45-60s, Annie VO, mock-UI visualizations,
caption rail) end-to-end.
Six skills added byte-identical in both mirror dirs:
- changelog-video (pipeline entry point)
- motion-doctrine (carries seam-stamp.mjs + seam-gate.mjs)
- cut-the-curve, captions-overlay, seam-craft, oversized-cursor
Layout:
- .claude/skills/ - Claude Code project-local auto-discover
- .agents/skills/ - Codex CLI project-local auto-discover (verified via
Magi's clean-home Codex 0.144.3 repro; NOT .codex/skills/)
Fonts, animated background (12 MB), house BGM (5 MB), lexicon, and
align-captions ship inside the skill dirs. .gitattributes routes only
.claude/skills/**/*.{mp4,mp3} + .agents/skills/**/*.{mp4,mp3} through
LFS — narrowly scoped so unrelated Player, Studio, registry, and
marketplace media stay put. HeyGen CLI auth is the one credential the
skill needs; Node >= 22, ffmpeg, and headless Chrome are documented
alongside in both READMEs.
.gitignore: rewrites .claude/ and .agents/ blocks to keep agent-installed
skill hygiene while re-including the six repo-native skill dirs plus
README.md.
CI:
- Extends changes.skills filter to match .claude/skills/**,
.agents/skills/**, scripts/lint-skills.ts, and scripts/check-skill-mirror.mjs.
- New 'Skills: project-native lint + mirror' job runs the extended
lint-skills.ts (schema-driven; required { name, description } + optional
{ license, allowed-tools, metadata }, name pattern check, description
length check) plus a new check-skill-mirror.mjs byte-integrity script
(24 mirrored files must match; README.md deliberately per-CLI).
- Wired into 'bun run lint' locally.
Frontmatter validator:
- Rejects unsupported top-level keys (catches category:-style drift).
- Requires name + description.
- Validates name pattern (^[a-z][a-z0-9-]{0,63}$) and description shape
(non-empty, <=1024 chars).
- Missing frontmatter block itself is a first-class error.
Also strips unsupported top-level 'category:' frontmatter from Jake's
motion-doctrine and cut-the-curve SKILL.mds (both mirrors), rewrites the
TTS invocation from ~/.claude/skills/media-use/... to the tracked
skills/hyperframes-media/scripts/heygen-tts.mjs, swaps npx hyperframes@latest
for the repo-local CLI in the gate step, and fixes a lint issue in Jake's
seam-gate.mjs (ternary-for-side-effect -> if/else).
Validated end-to-end by Home on Jun 23-29 (MP4 posted in C0ACCNHLG3U
thread 1784181166.041319). Independently reviewed R1/R2/R3 by Magi.
Co-authored-by: Jake Moran <jake@heygen.com>
51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# Project-local Codex CLI skills
|
||
|
||
Skills in this directory are auto-discovered by Codex CLI (verified against
|
||
Codex 0.144.3) when the `hyperframes` repo is opened as the working
|
||
directory. They are NOT part of the marketplace-distributed plugin (that
|
||
set lives under `skills/` and is manifested by `.codex-plugin/`). Two
|
||
separate namespaces, on purpose:
|
||
|
||
- `.agents/skills/` — **repo-native**, run only against this repo
|
||
(weekly changelog videos, doctrine-heavy authoring flows). Codex CLI's
|
||
project-local skill dir.
|
||
- `skills/` — **marketplace-distributable**, installed into other
|
||
projects via `npx hyperframes skills` or `npx skills add
|
||
heygen-com/hyperframes`.
|
||
|
||
## Weekly changelog video
|
||
|
||
The `changelog-video` skill turns a weekly changelog markdown into a
|
||
~45–60s branded 1080×1080 MP4 (motion-doctrine layout, Annie VO,
|
||
seam-gated cuts, caption rail). It ships pre-configured — fonts,
|
||
background pattern, house BGM, lexicon, and the align-captions script
|
||
all live inside `changelog-video/`. Its five dependency skills
|
||
(`motion-doctrine`, `cut-the-curve`, `captions-overlay`, `seam-craft`,
|
||
`oversized-cursor`) sit alongside so the router graph is complete on
|
||
clone.
|
||
|
||
Weekly usage:
|
||
|
||
1. Regenerate the digest markdown for the target range:
|
||
`bun run changelog:weekly --from YYYY-MM-DD --to YYYY-MM-DD` (this
|
||
only reads git; the `--write` variant is what the docs cron uses).
|
||
2. In Codex CLI at the repo root, invoke `/changelog-video` with the
|
||
generated markdown. The agent will present its script +
|
||
visualization plan for review before rendering.
|
||
3. Accept, and the agent produces `weekly-changelog-<range>.mp4` gated
|
||
by `hyperframes check` (0 errors) + `seam-gate verify` (0 fail/warn).
|
||
|
||
TTS uses the tracked `skills/hyperframes-media/scripts/heygen-tts.mjs`
|
||
(no extra install needed). Runtime dependencies you need on PATH:
|
||
|
||
- Node ≥ 22
|
||
- HeyGen CLI ≥ 0.3.0, authenticated via `heygen auth login --oauth`
|
||
- `ffmpeg` (for VO wav conversion + frame QA)
|
||
- A headless Chrome for HyperFrames rendering (`hyperframes doctor`
|
||
will point out the exact ask if it's missing)
|
||
|
||
The parallel set at `.claude/skills/` is a byte-identical copy so
|
||
Claude Code users get the same auto-discover behaviour — keep the two
|
||
in sync when editing. A `scripts/check-skill-mirror.mjs` check enforces
|
||
this at CI time.
|