ウォークスルーGIFスキル は何をしますか?
ブラウザ操作のウォークスルーを録画し、MP4 + GIFをエクスポートする自己完結型のNode.jsプロジェクトを生成します。
このスキルを使用すべき時 vs. claude-in-chrome gif_creator
ユーザーのライブブラウザセッション内(ユーザーのプロファイル、開いているタブ、ログイン済み状態)で簡単な一回限りのキャプチャを行う場合は、claude-in-chrome の gif_creator ツールの方がはるかにシンプルです。プロジェクトのスキャフォールディングやAPIキーは不要です。このスキルは、gif_creatorでは提供できないものが必要な場合に使用してください。再実行可能/バージョン管理可能なスクリプト(UI変更後に再録画)、MP4出力、高品質なgifski GIF、クリーンプロファイル録画(フレーム内に個人のブックマーク/拡張機能がない)、またはCIでの繰り返し実行が必要な場合です。
アーキテクチャ
自然言語による説明
↓
ClaudeがTypeScriptスクリプトを生成
↓
Stagehand v3 (AIブラウザ制御) — CDP経由でPlaywrightに接続
↓
Playwright録画コンテキストが動画(.webm)をキャプチャ
↓
ffmpegが変換 → .mp4
gifskiがフレームを変換 → .gif
↓
出力: walkthrough.mp4 + walkthrough.gif + walkthrough.md
ワークフロー
ステップ 1: 要件収集
前提条件 — LLM APIキー: StagehandはAIアクションごとにLLMを呼び出します。ユーザーは.envにANTHROPIC_API_KEY(または設定されたモデルに一致するプロバイダのキー、例: OPENAI_API_KEY)を用意する必要があります。これを事前に確認してください。キーがないと生成されたスクリプトは実行できません。
コードを生成する前に、以下を確認します。
- ターゲットURL — ウォークスルーはどこから始まりますか?(例:
https://app.example.com/login) - フローの説明 — どのような手順を実演すべきですか?(自然言語で問題ありません)
- 認証状況 — ページは公開されていますか、それともログインが必要ですか?ログインが必要な場合:
.envに認証情報をハードコードするか、事前認証済みセッション/クッキーのエクスポートを使用するか、ログイン済みの状態から開始しますか? - 出力形式 — GIFのみ、MP4のみ、または両方?(デフォルト: 両方)
- 長さ/ペース — 高速デモか、意図的なステップバイステップか?(デフォルトはステップ間の一時停止約1〜2秒)
- ビューポート — デフォルトは1280×800。モバイル風デモの場合はより狭くします。
ユーザーが最初に詳細な説明を提供する場合は、推測できる部分は推測し、不足している部分だけを質問します。
ステップ 2: プロジェクトの生成
./walkthrough-[name]/ に、完全で実行可能なプロジェクトを出力します。
walkthrough-[name]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ └── walkthrough.ts ← メインスクリプト
└── scripts/
└── convert.sh ← ffmpeg + gifski変換
Stagehand APIとステップ変換パターンについては references/stagehand-patterns.md を参照してください。
ffmpeg/gifski変換コマンドとGIFチューニングについては references/output-pipeline.md を参照してください。
ステップ 3: ステップの変換
ユーザーの自然言語を stagehand.act() 呼び出しに変換します(v3: act() はstagehandインスタンスに存在し、プレーンな文字列と variables や page などのオプションを受け取ります)。パターンと注意点については references/stagehand-patterns.md を参照してください。
主な変換ルール:
- 各論理的なUIアクション = 1回の
stagehand.act("...", { page })呼び出しと、明確な英語の指示 - 入力のタイプは
variables(%name%プレースホルダー)を介して行う — 指示文字列にシークレットをインラインで含めない - ペース調整のために主要なステップ間に
page.waitForTimeout(1500)を追加(視聴者に見えるように) - ナビゲーション後は
page.waitForLoadState('networkidle')を追加 - セレクタをハードコードしない — Stagehandは自然言語の指示からセレクタを判断する
- 認証が必要なフロー:
.envを認証情報に使用し、ハードコードしない
ステップ 4: 録画戦略
Playwright動画録画を常に主要なキャプチャ方法として使用します。
- Stagehand v3には組み込みの録画機能はありません —
chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() })でPlaywrightをStagehandのブラウザに接続し、recordVideoオプション付きのコンテキストを作成し、そのコンテキストのページを操作します(references/stagehand-patterns.mdを参照) - 録画コンテキストを介してセッション全体を
.webmとして録画 - 個々のスクリーンショットを直接GIFに結合しようとしない — 動画→フレーム→GIFの方が高品質
- スクリプト完了後、
convert.shを実行してMP4とGIFを生成
GIFを主要な成果物にしないでください。 常にMP4を最初に生成します。GIFはそこから派生します。GIFは15秒を超えるとサイズが大きく品質が低くなります。ユーザーに警告し、ウォークスルーを60秒未満に抑えることを推奨します。
ステップ 5: クリック/カーソルオーバーレイ(オプションだが推奨)
ウォークスルー開始前に page.addInitScript() を介してクリックハイライトオーバーレイを注入します。スニペットについては references/stagehand-patterns.md → 「クリックオーバーレイ」セクションを参照してください。
これにより、各クリックポイントに微妙な波紋アニメーションが追加され、後処理なしでウォークスルーが劇的に読みやすくなります。
ステップ 6: 出力
生成後、以下を出力します:
- プロジェクトディレクトリ(全ファイル)
- 会話内での簡単なセットアップチェックリスト:
## セットアップ
npm install
npx playwright install chromium
cp .env.example .env # ANTHROPIC_API_KEY と認証情報を入力
## 実行
npx tsx src/walkthrough.ts
## GIF + MP4に変換
bash scripts/convert.sh
また、ユーザーに予想される内容(おおよその長さ、ビューポートサイズ、出力ファイル名)を伝えます。
実行を提案する: Claude Codeはパイプライン全体(npm install、npx playwright install chromium、ウォークスルースクリプトの実行、bash scripts/convert.sh)を自分で実行できます。ユーザーが同意すれば可能です(ユーザーが .env の値を提供する必要があります)。自分で実行する場合は、成功を宣言する前に出力を確認してください。ffprobe でMP4の長さが妥当か確認し、GIF/MP4のファイルサイズが無視できない大きさであることを確認します(convert.sh は検証テールにこれらを出力します)。
警告 / 中止条件
以下のいずれかに該当する場合は、ユーザーに事前に伝えます。
| 条件 | ガイダンス |
|---|---|
| ページにMFA/SSOを使用したログインが必要 | スクリプトはこれを自動処理できません — ユーザーはログイン済みブラウザセッションからクッキーをエクスポートする必要があります |
| ターゲットページにCAPTCHAあり | Playwrightが停止します — 代わりにデモ/サンドボックス環境を使用してください |
| 激しいアニメーション / 無限スクロール | 録画はキャプチャしますが、GIF変換のサイズが大きくなります — クリッピングを推奨します |
| フローが90秒を超える | MP4のみを推奨します。GIFは使用できないほど大きくなります |
| ページコンテンツがランダム/動的 | Stagehandはビジュアルターゲティングを処理しますが、再実行すると見た目が異なる可能性があることを警告します |
出力命名規則
walkthrough-[slug]/
output/
walkthrough.webm ← Playwright生録画
walkthrough.mp4 ← 変換後(H.264、ウェブセーフ)
walkthrough.gif ← gifski出力、最大幅800px
walkthrough.md ← ステップバイステップの注釈(自動生成)
.md ファイルは、各 act() 呼び出しをタイムスタンプ付きの番号付きステップとしてリストします。GIFと共にキャプションとして埋め込むのに便利です。
参考ファイル
references/stagehand-patterns.md— Stagehand API、ステップ変換、クリックオーバーレイスニペット、認証パターンreferences/output-pipeline.md— ffmpegコマンド、gifskiフラグ、GIF最適化、トラブルシューティング