clickreel は何をしますか？
あなたはユーザーの実際のアプリのインタラクティブデモを作成しています。訪問者がランディングページやリンクから開き、ハイライトされた場所をクリックすると、アプリの次の実際の画面が表示されます。訪問者は1分以内にアプリを試す価値があるかどうかを判断します。良い結果は、アプリが得意とする1つのことを6～12回のクリックで示すものです。
ストーリーボードを書き、結果を評価するのはあなたです。Clickreelが残りの処理を行います。アプリをヘッドレスブラウザで開き、各ステップを実際に実行し、操作前後のページを撮影し、スクリーンとプレーヤーを1つのHTMLファイルにパッケージ化します。
コマンド
すべては1つのスクリプトで実行されます。必要なのはNodeと、マシンに既にインストールされているChromiumベースのブラウザだけです。
node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <command>
上記で${CLAUDE_SKILL_DIR}がリテラルテキストとして表示されている場合、エージェントがそれを入力していません。このSKILL.mdを含むフォルダを使用してください。
| コマンド | 動作 |
|---|---|
build <storyboard> | ステップを実行し、ストーリーボードの隣に<name>.html（デモ）と<name>.stops.png（コンタクトシート）を書き込みます。10～30秒かかります。 |
check <storyboard> | ステップを実行し、コンタクトシートのみを一時フォルダに書き込みます。プロジェクトに影響を与えずにストーリーボードを試すために使用します。 |
doctor | このマシンでデモをビルドできるかどうかを確認します。起動に失敗した場合は最初に実行してください。 |
init [file] | スターターストーリーボードを書き込みます。 |
便利なフラグ：--out <dir>、--json、--headed（ブラウザの動作を監視）、--force。
作業方法
1. デモで何を表示するかを決定する
1つのデモ、1つのフローです。このアプリが最も説得力のあることは何か自問し、その周りにデモを構築します。ユーザーが機能やフローを指定した場合、それが主題です。「デモを作って」とだけ言われた場合は、コアフロー（READMEの最初の文が約束していること）を自分で選び、どれを選んだかを伝えます。アプリにいくつかの無関係な製品がない限り、ユーザーに選択を求めないでください。
2. アプリを起動し、実際のラベルを調べる
アプリの起動方法（package.jsonのスクリプト、README、dist/フォルダ）を見つけます。次に、いずれかを選択します。
- 既に実行中、または自分で起動できる場合：
"url"を設定します。 - 静的サイトまたはビルド済みフォルダの場合：
"serve": "./dist"を設定すると、Clickreelがサーバーとして提供します。 - 後でビルドを再現可能にしたい場合：
"url"と共に"start": "npm run dev"を設定すると、Clickreelが起動して待機します。
ステップは、ユーザーが目にする単語（ボタンテキスト、フィールドのラベルやプレースホルダー、aria-label）によって要素をターゲットにします。選択したフローのコンポーネントを読み、ラベルを正確にコピーしてください。推測は無駄な往復を生みます。
デモは、表示する価値のある状態で開く必要があります。空の初回起動画面やログイン画面は弱いオープニングです。アプリにデータやログイン済みセッションが必要な場合は、最初のストップの前にそれをセットアップします：アプリのシードスクリプトを使用するか、localStorageに書き込むevalステップを使用するか、テストアカウントで最初にログインします。パスワードとトークンは環境変数に配置し、${env:NAME}として参照します。実際のシークレットをストーリーボードに決して書き込まないでください。
3. ストーリーボードを書く
特にユーザーが別の場所を希望しない限り、demo.click.jsonとしてプロジェクトルートに保存します。プロジェクトに既にDemoreelのストーリーボード（*.reel.json）がある場合は、そのファイルをそのままビルドできます。
{
"url": "http://localhost:5173",
"displayUrl": "acme.app",
"demo": {
"title": "Acme",
"intro": "プロジェクトがアイデアから完成までどのように進むかを見てみましょう。",
"cta": { "label": "無料で試す", "url": "https://acme.app/signup" }
},
"steps": [
{ "say": "数秒でプロジェクトを開始" },
{ "click": "新規プロジェクト" },
{ "type": "Webサイト開設", "into": "プロジェクト名" },
{ "click": "プロジェクトを作成" },
{ "say": "タイピングと同じ速さでタスクを追加" },
{ "type": "発表記事を書く", "into": "タスクを追加" },
{ "press": "Enter" }
]
}
各ステップはストップ（訪問者が何かをするもの）になるか、何にもなりません：
| ステップ | デモ上での動作 |
|---|---|
{ "click": "新規プロジェクト" } | 要素上のホットスポット。訪問者がクリックすると、実際の結果が表示されます。 |
{ "type": "hello", "into": "メールアドレス" } | フィールド上のホットスポット。クリックすると、テキストが入力される様子が再生されます。intoを省略すると、フォーカスされているフィールドへの入力を続けます。 |
{ "press": "Enter" } | クリックするキーキャップ、または訪問者が実際のキーを押します。"Mod+K"はmacOSではCmd、その他ではCtrlです。 |
{ "hover": "グラフ" } | ホバー、または電話でのタップに反応するホットスポット。 |
{ "select": "Pro", "in": "プラン" } | ネイティブドロップダウン上のホットスポット。 |
{ "say": "短い1行" } | その後のストップ中に表示されるキャプション。次のsayまで残ります。その後にストップがないsayは、「次へ」ボタン付きのカードになります。 |
{ "zoom": "合計" } | ノート：要素がハイライトされ、ページの残りが暗くなり、「次へ」ボタン付きのキャプションカードが表示されます。 |
{ "scroll": 600 }、{ "goto": "/settings" }、{ "wait": 800 }、{ "waitFor": "レポート準備完了" }、{ "eval": "..." } | ストップなし。デモは自動的に通過します。セットアップや適切な場所に移動するために使用します。 |
各ホットスポットの横の言葉は自動的に作成されます：「新規プロジェクト」をクリック、「Webサイト開設」と入力、キーキャップ付きの押す。ステップに"hint": "設定を開く"を追加すると、独自の方法で表示できます。これは、読み取り可能な名前がないセレクターを使用するステップの場合に行います（デフォルトは「ここをクリック」になります）。
ターゲットは表示名と照合され、最初に完全一致が試みられます。名前があいまいな場合は"nth": 2を追加するか、セレクターを使用します："css=.sidebar button"、"#save"、"testid=submit"。クッキーバナーを閉じるなど、操作するものがない可能性があるステップには"optional": trueを追加します。
ステップ、オプション、スタイル、フレームの完全なリストはreferences/storyboard.mdにあります。ここに示されていないものを使用する前に、それを読んでください。
4. ビルド
node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json
実行できないステップがあると、ビルドが停止し、何が問題かを正確に伝えます：
Step 4 (click "Creat project") failed: Could not find "Creat project" to click.
Did you mean: "Create project"?
On screen now: "Cancel", "Create project", "Project name"
Screenshot of the page at that moment: /tmp/clickreel/demo-123/step-04-failed.jpg
ステップを修正して再度ビルドします。プロジェクトに既にClickreelが作成していない<name>.htmlがある場合、ビルドはそれを置き換えることを拒否します：ストーリーボードに"name"を設定するか、--out <dir>を渡します。
成功したビルドでも、ノートが出力されることがあります。それらを読んでください。Note: Step 4 (...) changed nothing you can see on the pageは、ステップが操作するものを見つけたが、その後ページが同じように見えたことを意味します：ほとんどの場合、間違った要素を見つけており、デモ内のそのストップは何もしません。ターゲット（より正確な名前、nth、またはセレクター）を修正して、再度ビルドします。
5. 報告する前に結果を確認する
buildはコンタクトシート<name>.stops.pngを書き込みます：ストップごとに1枚の画像で、ホットスポットが描画され、その下にステップとキャプションが表示され、最後の画面が続きます。それを開いてすべての画像を確認します。これが自分のデモをチェックする方法です。
各画像で以下を確認します：
- ホットスポット。 ボックスが意図した要素上にあり、その要素が表示されていますか？間違ったものにボックスがある場合は、名前が別のものに一致したことを意味します：
nthまたはセレクターを使用します。 - 真実。 画像はアプリが機能していることを示していますか？エラーメッセージ、空の状態、終了しなかったスピナー、プレースホルダーテキストを探します。各画像は訪問者がクリックする前に見るものであり、その後の画像はクリックが何をしたかを示します。
- キャプション。 画像の下のキャプションは、画像内で何が起こっているかを説明していますか？
- 最後の画像。 エンドカードの後ろにあります。アプリの最も見栄えの良い状態であるべきです。
ストーリーボードを修正し、再度ビルドします。2～3回のラウンドが普通です。シートが正しく見えるようになったら停止します。
6. 引き渡す
ファイルの場所、サイズ、ストップ数、表示するフローをユーザーに伝えます。buildが出力した埋め込み行を提供します：
<iframe src="demo.html" title="Acme: インタラクティブデモ" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>
ファイルが何であるかを簡潔に伝えます：アプリの画像を含む1つのHTMLファイルで、ディスクおよび任意のWebホストから動作し、ネットワークからは何もロードしません。Clickreelが出力したノート（ページエラー、カバーされた要素、大きなファイル）を報告します。ステップを機能させることができずに削除した場合は、その旨を伝えます。
GitHubのREADMEはHTMLファイルを実行できません。READMEの場合は、デモがホストされている場所へのリンクを貼るか（GitHub Pagesはdocs/を適切に提供します）、DemoreelからのGIFを使用します。
良いデモを書くための要点
- 6～12のストップ。 すべてのストップは訪問者が行わなければならないクリックです。セットアップは削除するか、最初のストップの前に
evalで行います。 - キャプションは見出しであること。 7単語以内で、利点について（「タスクを完了としてマーク」）、アクションについてではありません（「チェックボックスをクリック」）。ヒントは既に何をクリックするかを示しています。デモ内のキャプションは3～5つ。
- 実際のものを入力する。 「テスト」や「asdf」ではなく「Webサイト開設」。入力されたテキストは売り込みの一部です。
- 開始と終了を適切に行う。 開始カードには
demo.titleと1行のdemo.introを設定します。アプリの最良の状態で終了し、demo.ctaに訪問者が次に進むべき場所を設定します。 - 配置場所に合わせてサイズを選ぶ。 デフォルトの
desktopビューポートはランディングページに適しています。モバイルWebアプリの場合は"viewport": "phone"を使用します。ビューポートが小さいと、小さな埋め込み内でアプリが大きく見えます。
構造、ノート、自動再生、デモのイベントリッスンの詳細については、references/writing.mdを参照してください。
プライバシーと誠実さ
- すべてはこのマシン上で実行されます。Clickreelは独自のネットワーク接続を開きません。ブラウザはあなたが指定したアプリのみをロードします。完成したファイルはリクエストを一切行わず、何も追跡しません。
- デモはページ上のものの画像で構成されており、公開されることを意図しています。テストアカウントと架空のデータを使用してください。ユーザーの同意なしに、実際の顧客データ、実際のメールアドレス、内部URLをキャプチャしないでください。
- アプリをありのままに表示します。機能を偽装したり、実際のエラーを隠したり、何かを実際よりも速く見せかけたりするために
evalを使用しないでください。データのシードと開発者オーバーレイの非表示は問題ありませんが、動作をでっち上げることは許されません。
できないこと
Webアプリのみ。画面は画像なので、訪問者はストップ内でスクロールしたり、テキストを選択したり、選択したパスから外れたりすることはできません。dragステップは、そのホットスポットがクリックされたときに再生されます。新しいタブを開くリンクは追従せず、iframeの内部にはアクセスできず、ファイルをアップロードすることはできません。ネイティブのalert()およびconfirm()ボックスは自動的に受け入れられ、表示されません。フローがこれらのいずれかに依存する場合は、その旨を伝え、機能する部分を構築します。
エラーメッセージで説明されない方法で何かが失敗した場合は、references/troubleshooting.mdを参照してください。