HyperFrames Ops
環境に関する質問を受ける前に、まず同じディレクトリの experience.local.md を読み、このマシンに関する最新の事実（プロキシコマンド、バージョンスナップショット、過去の Q&A）を取得してください。
零、なぜ独立した Ops レイヤーが必要か
サードパーティのスキルは通常、汎用的な能力のみを記述し、各マシンのネットワーク、プロキシ、Node/FFmpeg のバージョン、フォントキャッシュ、ログイン状態、ツールの組み合わせを事前に把握することはできません。公式スキルを直接変更すると、更新時の競合が発生し、またローカル環境の事実を上流の汎用説明に混在させてしまうことになります。
そのため、2 つのレイヤーを分離します：
- 公式スキルは能力の源泉であり、更新・交換可能な状態を維持します。
hyperframes-opsはローカル環境適応レイヤーであり、ベストプラクティス、互換性の差異、失敗パターン、および検証済みの回避策を記録します。- 制作上の問題が発生した場合は、まず公式スキルを読みます。環境、組み合わせ、バージョン、またはローカル環境適応の問題が発生した場合にのみ、本スキルを読みます。
- 上流の更新により古い経験が無効になった場合は、ローカルの経験ファイルで無効をマークし、再検証を行います。古い経験を新しい動作に上書きして使用することはありません。
一、プロジェクトの基本情報（普遍的事実）
- HyperFrames は HeyGen 公式 のオープンソースプロジェクトです：
github.com/heygen-com/hyperframes、npm パッケージ名はhyperframes - 位置づけ：HTML で動画合成を記述し、ヘッドレス Chrome で MP4 にレンダリングする CLI（
npx hyperframes） - 環境要件：Node.js >= 22、FFmpeg
二、公式スキルの配布メカニズム
- 公式スキルは CLI と同じリポジトリで管理・バージョン管理され、マニフェストはリポジトリルートにあります：
https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json - 構成：コアセット（hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes）+ ワークフローセット（general-video、slideshow、motion-graphics、music-to-video、pr-to-video、product-launch-video、website-to-video、faceless-explainer、talking-head-recut、embedded-captions、media-use、figma）。実際のスキル一覧は
skills checkの出力に従ってください - 管理コマンド：
npx hyperframes skills check—— マニフェストと照合してバージョンを確認npx hyperframes skills update—— インストール済みスキルをすべて更新し、公式が廃止したスキルをクリーンアップnpx hyperframes init—— スキルを最新の状態に強制的に同期（--skip-skillsは現在公式で無効化されています）
- インストール場所：グローバル
~/.claude/skills/（CLI が claude-code を自動認識） - 命名の安全性：
skills updateのクリーンアップロジックはロックファイルに基づき「ソースの帰属」を判断し、公式リポジトリ由来で現在廃止されたスキルのみを削除します。本スキルはhyperframes-で始まりますが、公式ロックの帰属には含まれないため、公式アップデーターによって誤って削除されることはありません
三、トラブルシューティングルート
| 症状 | ルート |
|---|---|
skills check/update/init が AbortError（fetchManifest タイムアウト）をスローする | ネットワーク問題：CLI は Node 組み込み fetch を使用して raw.githubusercontent.com にアクセスします。直接接続できない場合はプロキシを使用する必要があります。experience.local.md を読み、このマシンでそのまま使えるコマンドを取得してください |
npx hyperframes のその他のネットワーク関連の失敗 | 同上。Node 組み込み fetch（undici）はデフォルトで HTTP_PROXY 環境変数を読み取りません。Node 24+ では NODE_USE_ENV_PROXY=1（または --use-env-proxy）を追加する必要があります |
| レンダリング/プレビュー環境の異常 | npx hyperframes doctor、npx hyperframes browser でセルフチェック。Node >= 22、FFmpeg が利用可能であることを確認 |
| スキルの動作が古いバージョンに見える | skills check でバージョンの差を確認し、skills update で最新に揃える |
heygen auth login --oauth のトークン交換失敗（api2.heygen.com connection refused）またはミュージックライブラリ呼び出しのタイムアウト | heygen CLI は Go プログラムであり、HTTP(S)_PROXY 環境変数を認識します（Node fetch とは逆で、追加のスイッチは不要です）。ネットワーク制限のある環境では、すべての heygen コマンドはプロキシとともに実行する必要があります。OAuth コールバックサービスは 5 分間のみ有効で、対話型シェルが必要です（バックグラウンド/nohup で起動すると、コールバックを受信できずタイムアウトします）。このマシン用のコマンドは experience.local.md にあります |
| レンダリング結果のフォントが正しくない（タイトルが広がる、コンテナからはみ出す、lint/inspect がすべてパスしているにもかかわらず） | 内蔵 18 フォントは実行時にオンデマンドでネットワークから取得 されます（@fontsource → ~/.cache/hyperframes/fonts）。取得に失敗すると、静かにシステムフォントにフォールバックします。ネットワーク制限環境での対策：woff2 ファイルをプロジェクト内にダウンロードし、明示的に @font-face でセルフホスティングする |
| 制作関連の問題（合成の書き方、アニメーション、レンダリングパラメータなど） | 本スキルでは対応しません。公式の hyperframes エントリスキルのルーティングテーブルに従ってください |
四、経験の書き戻しプロトコル
- experience.local.md に書き込む（このマシン限定、このディレクトリの .gitignore で無視されています）：新たに遭遇した問題と検証済みの解決策、バージョン/インストール状態のスナップショット（日付付き）、このマシン固有のコマンド、プロキシとネットワークに関する事実、過去の Q&A
- この SKILL.md に書き戻す（git で管理、共有可能）：公式メカニズムの変更（配布方法、コマンドのセマンティクス、クリーンアップロジック）、新しい汎用トラブルシューティングルート
- 判断基準：別のマシンでも成立する内容 → SKILL.md；このマシンにのみ成立する内容 → experience.local.md
- HyperFrames の環境問題が原因で呼び出され、解決されたたびに、上記のレイヤー分けに従って結論を書き戻し、日付を付記します。