Communitygithub.com

simpletibr/simplicio-loop-marketing

ワンショットでHyperFrames(https://github.com/wesleysimplicio/hyperframes)をマーケティングエンジンクローンに第一級のビデオプロバイダーとして組み込むブートストラップスキルです。3つのランタイムスキル、プロバイダークラス+モック、ルーティングマトリクス行、環境変数、CLAUDE.mdの更新を冪等に実行します。新しいクローンにHyperFramesを追加する場合や、リベースで統合の一部が欠落した場合に呼び出します。

simplicio-loop-marketing とは?

このスキルは、マーケティングエンジンクローンにHyperFramesをビデオプロバイダーとして統合するための、完全に手順化された冪等なブートストラップツールです。主にClaude CodeなどのAIエージェント向けに設計されており、9つのステップで構成されたチェックリストに従って、3つのランタイムスキル(hyperframes、hyperframes-cli、hyperframes-prompt-builder)の作成、ディスパッチャースキルの更新、プロバイダーレイヤーの拡張、ルーティングマトリクスと環境設定の更新、そしてCLAUDE.mdの変更を自動的に行います。各ステップは冪等であるため、既に統合済みのリポジトリに再実行しても影響はなく、mainブランチへのコミットを防ぐ安全機構も備えています。このスキルは、新規クローンへのHyperFrames追加や、リベース後に統合が壊れた場合の修復に特に有用です。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/install-hyperframes

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HyperFrames のインストール

HyperFrames をビデオプロバイダーとして追加する統合を、CLAUDE.md に記載された3ステップ「新しいプロバイダーの追加」契約に従って、1パスで再現します。存在すべきすべてのアーティファクトの自己完結型チェックリストであり、不足しているものだけを検証して作成します。

このスキルは、統合をゼロから再導出する代わりに実行してください。このリポジトリにおいて「HyperFrames が配線されている」という状態の正規の記録です。

呼び出すタイミング

  • HyperFrames サポートがまだない新しいマーケティングエンジンクローン。
  • リベースまたはマージで、以下のアーティファクトのいずれかが欠落した場合(router:check が警告を出す、ビデオルーティングがタイポグラフィタスクで higgsfield にフォールバックする、.skills/hyperframes*/ が存在しないなど)。
  • 新しいクライアントがプログラム的なショート動画、モーションタイポグラフィ、データビジュアライゼーションリールを必要とし、マトリクスに3つのタスク種別を配線する必要がある場合。
  • 新しいオペレーターをオンボーディングする際に、3つのコミットを読む代わりに単一のコマンド可能なプレイブックが必要な場合。

入力

  • repo_root: 文字列。マーケティングエンジンクローンの絶対パス。デフォルトは process.cwd()。
  • branch: 文字列、オプション。コミットするブランチ。デフォルトは claude/install-hyperframes。ブランチが存在しない場合は作成します。main には決してコミットしません。
  • dry_run: ブール値、オプション。true の場合、計画された変更を出力して終了し、書き込みは行いません。

プロセス

各ステップを順番に実行します。各ステップは冪等です。すでに統合済みのリポジトリで再実行しても、そのステップは何も行いません。

ステップ 1 — 事前確認

  1. repo_root に CLAUDE.md が含まれ、その中に行 ## How to Add a New Provider が存在することを確認します。存在しない場合は実行を拒否します。これはマーケティングエンジンリポジトリではありません。
  2. lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts、lib/providers/__mocks__/video.ts が存在することを確認します。いずれかが欠けている場合は実行を拒否します。
  3. アクティブなブランチが main ではないことを確認します。main にいる場合は、最初に branch を作成してチェックアウトします。

ステップ 2 — 3つのランタイムスキルを追加

以下の3つのディレクトリを SKILL.md ファイルとともに作成します。各ファイルはツリー内の正規バージョンとしてすでに存在しています。以下の「参考アーティファクトセット」セクションからそのままコピーしてください。ファイルがすでに存在し、そのフロントマターの name が一致する場合はスキップします。

  • .skills/hyperframes/SKILL.md — コンポジションオーサリングルール(レイアウト優先アニメーション、一時停止して window.__timelines に登録されたタイムライン、Math.random()/時間ベースのロジック禁止、data-composition-variables 経由で宣言される変数)。
  • .skills/hyperframes-cli/SKILL.md — npx hyperframes の lint → inspect → render 開発ループ。常に --strict --strict-variables でレンダリングします。
  • .skills/hyperframes-prompt-builder/SKILL.md — マトリクスが hyperframes に解決されたときに video-prompt-builder によって呼び出されるスペシャリスト。clients/<slug>/design.md からブランドトークンを読み込み、task_kind ごとにテンプレートを選択し、コンポジション仕様とレンダリング引数を返します。

ステップ 3 — ディスパッチャースキルを更新

.skills/video-prompt-builder/SKILL.md において:

  1. 冒頭の段落と「関連スキル」セクションのスペシャリストリストに hyperframes-prompt-builder を追加します。
  2. task_kind 入力列挙型に motion_typography、data_viz_reel、programmatic_short を追加します。
  3. 環境変数を検証する「プロセス」ステップで、リストに HYPERFRAMES_ACTIVE を追加します。
  4. プロバイダー→スペシャリストマッピングに行 Hyperframes -> hyperframes-prompt-builder を追加します。
  5. 例を追加します:task_kind: programmatic_short で HyperFrames にルーティングされる週次 KPI リール。

ターゲット文字列がすでに存在するサブステップはスキップします。

ステップ 4 — プロバイダーレイヤーを拡張

lib/providers/types.ts において、VideoTask ユニオンに3つのメンバーを追加します:

| "motion-typography"
| "data-viz-reel"
| "programmatic-short"

lib/providers/matrix.ts において:

  • EMBEDDED_DEFAULTS.video に3行を追加します:motion-typography、data-viz-reel、programmatic-short – それぞれデフォルトで hyperframes になります。
  • TASK_LABEL_MAP にラベルエイリアスを追加します:"motion typography"、"kinetic typography"、"data viz reel"、"data-viz reel"、"programmatic short"、"parametrized short"。

lib/providers/video.ts において:

  • RealVideoBase を拡張し、process.env.HYPERFRAMES_ACTIVE === "true" でガードされる HyperframesVideoProvider クラスを追加します。realGenerate からは「呼び出し元コンテキストでローカル CLI レンダリングが必要;スタブ」エラーをスローします(既存の higgsfield/topview スタブパターンと同様)。
  • REAL_VIDEO_REGISTRY に hyperframes: () => new HyperframesVideoProvider() を登録します。

lib/providers/__mocks__/video.ts において:

  • BaseMockVideo を拡張し、name = "hyperframes" を持つ MockHyperframesVideoProvider を追加します。
  • MOCK_VIDEO_REGISTRY に hyperframes: () => new MockHyperframesVideoProvider() を登録します。

ステップ 5 — ルーティングマトリクスファイルを更新

.specs/architecture/PROVIDERS.md において、「ビデオルーティング」テーブルに3行を追加します:

| モーションタイポグラフィ | hyperframes | HTML/GSAP キネティックタイプ、ブランド忠実、決定論的 |
| データビズリール | hyperframes | 宣言された変数 → 再レンダリング可能なチャート(NYT スタイル) |
| プログラマティックショート | hyperframes | パラメータ化された HTML コンポジション;バイト同一の再レンダリング |

ステップ 6 — .env.example を更新

WAVESPEED_API_KEY= の後に追加します:

# HyperFrames はローカル HTML→MP4 レンダラーです。API キーは不要です。
# ローカルで `npx hyperframes doctor` が成功したら HYPERFRAMES_ACTIVE=true を設定します
# (Node >= 22、FFmpeg が PATH に必要)。https://github.com/wesleysimplicio/hyperframes を参照
HYPERFRAMES_ACTIVE=false

ステップ 7 — CLAUDE.md を更新

  1. 「スタック」テーブルで、「ビデオ」行のプロバイダーセルに hyperframes (ローカル HTML→MP4) を含めるように変更します。
  2. 「利用可能なスキル」で、wavespeed-batch の後に3行を挿入します:
    • hyperframes — HTML を真実のソースとするモーションコンポジションオーサリング。
    • hyperframes-cli — npx hyperframes の lint/inspect/preview/render を実行します。
    • hyperframes-prompt-builder — マトリクスが hyperframes に解決されたときに video-prompt-builder によって選択されます。

ステップ 8 — 検証

  1. 以下のテストを使用して .specs/architecture/PROVIDERS.md を解析し、motion-typography、data-viz-reel、programmatic-short がすべて hyperframes に解決されることをアサートします。
  2. npm run typecheck を実行します — 変更とは無関係な既存の失敗(例:@types/node の欠落)は許容しますが、プロバイダーレイヤーを参照する新しい TS エラーがあれば失敗とします。
  3. リポジトリに .env が存在する場合は npm run router:check を実行します。それ以外はスキップします(スクリプトは .env を必要とし、統合の形状とは無関係です)。
  4. git status が期待されるファイルのみを示すことを確認します。
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
  if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
    console.error('MISSING:', key); process.exit(1);
  }
}
console.log('PROVIDERS.md OK');
"

ステップ 9 — コミットしてプッシュ

  1. このスキルが触れたファイルだけをステージングします。git add -A は絶対に行わないでください。
  2. 正規のメッセージでコミットします:
    feat(skills): HyperFrames をビデオプロバイダーとして配線
    
    さらに、3ステップ契約の実行を説明するボディを追加します(マージされた参照コミットの文言を参照)。
  3. origin <branch> にプッシュします。ブランチにドラフト PR が存在しない場合は作成します。

出力

  • branch: 文字列。コミットを保持するブランチ。
  • pr_url: 文字列。作成されたかすでに存在した場合のドラフト PR の URL。
  • files_written: 実際に作成または変更された相対パスの配列。
  • files_skipped_idempotent: すでに正しかったためにスキップされた相対パスの配列。
  • verification: { providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }。

絶対的なルール

  • 冪等。 すでに統合済みのリポジトリで再実行しても、ファイルには触れません。
  • main には決してコミットしない。 最初にフィーチャーブランチを作成します。エンジンのブランチポリシーは上流で強制されます。
  • スキル本文では契約外で hyperframes に言及しない。 プロバイダー選択は依然として PROVIDERS.md + lib/router.ts を通じて行われます。このスキルはブートストラップです。ランタイム選択はプロバイダーに依存しません。
  • レンダリングされた MP4 や outputs/ 以下のファイルは編集しない。 このスキルはエンジンの配管のみを変更します。
  • 既存の compliance-<アクティブなクライアント> スキルやクライアント固有のアーティファクトは決して削除しない。 統合は追加的なものです。

障害モード

  • ステップ1の事前確認が失敗した場合(マーケティングエンジンリポジトリではない):不足しているファイルを表示し、停止します。「修正」しようとしないでください。
  • 競合するコンテンツを持つファイルがすでに存在する場合(例:.skills/hyperframes/SKILL.md が手動編集された):正規のコンテンツとの差分を表示し、上書きする前にオペレーターに確認します。
  • npm run typecheck が lib/providers/ に新しい TS エラーを報告した場合:停止し、エラーを表示し、コミットしません。
  • git push がネットワーク以外の理由で失敗した場合:停止します。ネットワーク障害はプロジェクトの git ポリシー(2秒、4秒、8秒、16秒のバックオフ、最大4回)に従って再試行されます。

関連スキル

  • hyperframes: ランタイムオーサリング(このスキルによってステップ2でインストールされます)。
  • hyperframes-cli: ランタイム lint/inspect/render(このスキルによってステップ2でインストールされます)。
  • hyperframes-prompt-builder: ランタイムスペシャリスト(このスキルによってステップ2でインストールされます)。
  • video-prompt-builder: このスキルによってステップ3で更新されるディスパッチャー。
  • llm-router: 無関係。LLM プロバイダールーティングは並行したディスパッチャーです。

参考アーティファクトセット

このスキルが書き込むすべてのファイルの正規の内容は、main のマージされたコミットにあります:

  • スキル: .skills/hyperframes/SKILL.md、.skills/hyperframes-cli/SKILL.md、.skills/hyperframes-prompt-builder/SKILL.md
  • プロバイダーレイヤー: lib/providers/types.ts、lib/providers/matrix.ts、lib/providers/video.ts、lib/providers/__mocks__/video.ts
  • ルーティングマトリクス: .specs/architecture/PROVIDERS.md
  • 環境設定: .env.example
  • 憲章: CLAUDE.md

疑問がある場合は、origin/main のマージされた参照コミットとの差分を確認し、正規のバージョンをそのままコピーしてください。記憶から再入力しないでください。

上流参照

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

関連スキル