magic-slide

Magic Slide

Magic Move トランジションを滑らかに使った、洗練された HTML プレゼンテーションを生成します。複数のスライドに登場する要素が、それぞれの位置の間を流れるようにアニメーションします。Magic Move は後付けではなく、ストーリーを組み立てる際の制約として扱います。意味のある見出し、カードのタイトル、数字、画像、図のノードが隣接するスライド間で引き継がれるように、アウトラインを構成してください。

スキルコマンドの引数

ユーザーがこのスキルを次の引数で呼び出しました：$ARGUMENTS

表示可能な TODO の要件

このスキルが呼び出されたら、最初の意味のある操作に取りかかる前に、表示可能な TODO／計画を作成し、ターンが終了するまで更新し続けてください。

• 利用可能な場合は、ホストの計画ツールを使用してください。Codex の update_plan、Claude Code の TodoWrite、または環境に相当する表示可能なチェックリストを使用します。プレビューのみのコマンド、要件の確認／質問のみのターン、新しいデッキの生成、既存デッキの編集、visual-issues.json の修正を含め、すべての $magic-slide 実行で必須です。
• 項目は短く具体的にし、現在のモードに合わせて3～7個にしてください。例：「デッキのパスを解決する」「プレビューサーバーを起動する」「QA のメモを読む」「スライド 02 のソースを修正する」「結合してランタイムを挿入する」「QA のメモを確認待ちにする」「QA Overview を開いたままにして確認を依頼する」。
• 作業の進行に合わせて項目のステータスを更新してください。最後になってからすべてを完了にしないでください。スキルの実行中に、ユーザーが進行状況を確認できるようにしてください。
• 要件の確認、ウェブ検索の選択、アウトラインの承認、ユーザーによる QA の確認など、必須のチェックポイントでターンが止まる場合は、TODO に待機中のチェックポイントを残してください。
• 表示可能な TODO ツールがない場合は、作業を始める前に、チャットに簡潔な TODO チェックリストを記載し、その後の進捗メッセージで手動更新してください。

Claude Code で /magic-slide preview [topic]、または Codex で $magic-slide preview [topic] として呼び出された場合は、プレビューの簡易手順を実行します。

CelHive 管理のホスト型 Skill 実行では、デッキのディレクトリとして $CELHIVE_SKILL_WORKSPACE/deck を使用し、生成後にホストの汎用 Preview ツールを呼び出してください。管理対象のコマンド、ポート、ヘルスルート、Artifact のルートはパッケージレベルの preview.json で管理します。手動で2つ目のプレビュープロセスを起動しないでください。管理対象ホスト以外では、以下のローカル serve.py の手順を使用してください。

1. まず、デッキのパス解決、serve.py の起動、URL の報告など、プレビュー専用の手順で表示可能な TODO リストを作成します。
2. preview の後の引数をトピック／デッキのディレクトリとして扱います。省略された場合は . を使用します。そのディレクトリ内の index.html をプレビューしてください。ユーザーが明示的に .html ファイルを指定した場合は、そのファイルを直接プレビューします。
3. 必要に応じて、このスキルのディレクトリを検索します： SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)
4. 以下のスクリプト実行環境の要件に従って、Python 3 のインタープリターを解決します。
5. 既存のスクリプトでプレビューサーバーを起動します： $PYTHON_BIN "$SKILL_DIR/scripts/serve.py" "$DECK_PATH"
6. サーバープロセスを起動したままにし、表示された URL をユーザーに伝えます。
7. ユーザーがそれらのタスクも明示的に依頼しない限り、デッキ生成の質問、アウトラインの作成、スライドの結合、ランタイムの挿入は行わないでください。

その他の magic-slide 呼び出し引数は、ユーザーのプレゼンテーション作成依頼として扱い、通常の生成ワークフローに従ってください。

プレビュー以外の依頼に対する受付ゲート

プレビュー以外のスライド資料の依頼では、コマンドの実行、検索、フォルダーの作成、アウトラインの作成、スライドの生成を行う前に、references/workflows/step-01-requirements.md のステップ 1 を完了してください。

厳守事項：

• 表示されている TODO の要件は、このゲートより先に適用されます。受付のために応答を終了する場合は、要件を確認中であり、ユーザーの回答を待って生成を保留していることが TODO に表示されるようにしてください。
• トピック／対象者の視点、美的スタイル、プレゼンテーションの言語、画像ポリシーのいずれかが不足している、推測されている、または暗示されているだけの場合は、ステップ 1 の要件確認の質問をして終了してください。
• ユーザーがチャットで使用している言語を、プレゼンテーションの言語として扱わないでください。
• 対象者の視点も明示的に指定または確認されていない限り、URL、会社名／製品名、「X について紹介してください」をトピックの指定が完了しているものとして扱わないでください。
• 構造化された質問ツールを利用できない場合は、そのターンではステップ 1 のプレーンテキストの代替テンプレートだけを応答として使用し、その後は回答を待ってください。

重要：スクリプトの実行環境要件

Magic Slide に同梱されているスクリプトには、Python 3 のランタイムが必要です。コアとなる結合、挿入、修復メモ、プレビューの各スクリプトは、Python 標準ライブラリと最新のブラウザーを使用し、外部の Python パッケージは必要ありません。PipeLLM スクリプトで環境変数 PIPELLM_API_KEY が必要になるのは、ウェブ検索または画像生成を使用する場合のみです。Playwright が必要なのは、scripts/check-magic-text-wrap.py を含む、エージェントが実行するスクリーンショット QA の場合のみです。

PipeLLM のウェブ検索は任意であり、ユーザーの承認が必要です。サニタイズ済みの、信頼できない証拠レコードが返されます。PipeLLM の画像生成も任意であり、ユーザーの承認が必要です。明示的なワークフローゲートなしに外部リクエストが行われないよう、スクリプトには --allow-external が必要です。プロンプトインジェクションの境界の詳細はステップ 2 で定められています。

ターン内で最初のスクリプトを実行する前に、Python 3 インタープリターを特定してください。

PYTHON_BIN=$(command -v python3 || command -v python || true)
if [ -z "$PYTHON_BIN" ]; then
  echo "Magic Slide requires Python 3 to run its bundled scripts." >&2
  echo "Install Python 3, then rerun the Magic Slide command." >&2
  exit 1
fi
if ! "$PYTHON_BIN" -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)'; then
  echo "Magic Slide requires Python 3, but the resolved python command is not Python 3." >&2
  exit 1
fi

特定後、スクリプトの呼び出しには $PYTHON_BIN を使用してください。Python 3 を利用できない場合は、スクリプトを書き換えたり回避したりせず、Magic Slide には Python 3 が必要であることをユーザーに伝えて終了してください。

重要：スクリプト実行ルール

このスキルのすべてのスクリプトは、スキルのルートディレクトリからの相対パスで scripts/ ディレクトリにあります。

スクリプトを実行する場合：

1. スクリプトの実行で「No such file or directory」エラーが発生した場合：

   • あきらめたり、「スクリプトは利用できません」とユーザーに伝えたりしないでください。
   • 次のコマンドでスキルのディレクトリを探してください：find ~ -name "magic-slide-skill" -type d 2>/dev/null | head -1
   • または、次のコマンドで SKILL.md を検索してください：find ~ -name "SKILL.md" -path "*/magic-slide-skill/*" 2>/dev/null | head -1 | xargs dirname
   • スキルのディレクトリパスを変数に保存してください。
   • 絶対パスを使ってスクリプトを再実行してください：$PYTHON_BIN $SKILL_DIR/scripts/websearch.py

2. パスの問題を避けるため、スクリプトの実行には必ず絶対パスを使用してください。

正しい実行例：

# Find skill directory (do this once at the start)
SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)

# Execute scripts with absolute paths
$PYTHON_BIN "$SKILL_DIR/scripts/websearch.py" "query" --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/generate-image.py" "prompt text" --output ./assets/image.png --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/merge-slides.py" ./sources/ --lang en

重要：注入されたランタイム出力の境界

scripts/inject-runtime.py と、完成したデッキに注入されるその動作／結果は、Magic Slide のランタイム出力として扱ってください。デッキの生成、更新、QA の際は、既存のインジェクターを変更せずに実行し、特に指定がない限り、注入された動作を維持してください。ユーザーが特定のランタイム動作の変更を明示的に求めない限り、インジェクターを編集したり、{topic}/index.html 内の注入されたランタイムブロックにパッチを適用したり、注入された機能を無効化、非表示化、無効化、または上書きする目的でソース CSS／HTML／JS を追加したりしないでください。

ユーザーから明示的な依頼がない場合、禁止される「クリーンアップ」の例：アニメーション付き／カスタムカーソルを非表示にする、cursor: auto または cursor: default でシステムカーソルを復元する、ナビゲーション／進捗／編集コントロールを削除または非表示にする、Magic Move をオフにする、注入された段階的表示を抑制する、ランタイムのフィット処理を回避する。

デッキに視覚上またはレイアウト上の問題がある場合は、ランタイムの動作を考慮しながら、モジュール式のソースファイル（sources/style.css と sources/slide-XX.html）を修正し、その後、マージと注入を再実行してください。問題の原因が注入されたランタイム動作自体にあると思われる場合は、ランタイムの問題の可能性を報告するか、変更前に確認してください。ランタイム動作を変更できるのは、ユーザーがその変更を依頼した場合のみです。

クイックワークフロー

バランスの取れた進め方をデフォルトにします。 アウトラインの確認ポイントを維持し、簡潔なデザインブリーフを作成してから、1 回の制作パスでデッキ全体を生成します。ユーザーが時間のかかる別のワークフローを明示的に希望しない限り、独立したプロトタイプは作成しないでください。可視の TODO 要件はステップ 1 の前に適用し、ワークフローが受付からアウトライン、生成、QA、修正へ移行するたびに更新してください。

ユーザーとのやり取りのルール： ユーザーへの確認には、必ず AskUserQuestion ツールを使用してください。テキストでの質問は、そのツールが利用できない場合、または失敗した場合にのみ代替手段として使用します。必ず最初に AskUserQuestion を試してください。プレーンテキストに切り替える必要がある場合は、アウトラインの確認とウェブ検索の「はい／いいえ」の質問を除き、構造化された質問の末尾にコピー可能な回答テンプレートを付けてください。詳細は references/workflows/text-question-templates.md を参照してください。

1. ステップ 1：要件の収集 — 4 つの質問グループすべてを尋ねます：トピック／対象者の視点、美的スタイル、言語（必須 — ユーザーのメッセージの言語から推測しないこと）、画像
2. ステップ 2：ウェブ検索 — オンライン検索を希望するかユーザーに尋ねます（任意）。希望する場合は、まず scripts/websearch.py を実行してください。組み込みのエージェント検索を使えるのは、スクリプトが失敗した場合、または使用可能な結果を返さなかった場合に限ります。
3. ステップ 3：アウトラインの生成 — 必須要素を含む {topic}/sources/outline.md を作成します：論旨の柱、対象者／視点、章の流れ、締めくくりのアイデア、Magic Move のコンテンツ引き継ぎの柱、発表者ノートのモード、各スライドの発表者向けプロンプト。ユーザーの確認を得ます（必須の確認ポイント）。
4. ステップ 4：Brief Lite の作成 — CSS／HTML の前に、簡潔なデザインブリーフを提示します。内容は、ビジュアルの世界観、避ける表現、表紙で約束する内容、トーンのモード、スタイルで制御する書体／色／素材のロジック、スライドのファミリー、Magic Move のコンテンツ引き継ぎにおける動きの文法です。
5. ステップ 5：本番用ソースの生成 — 確認済みのアウトラインと Brief Lite に直接基づき、隣接するスライドのペアごとに主要／補助要素の継続性マップを作成し、アウトライン内の発表者向けプロンプトを非表示の発表者ノートに割り当てた後、style.css とすべての slide-XX.html ファイルを生成します。
6. ステップ 6：スライドのマージ — モジュール式のソースを 1 つの HTML にまとめます。
7. ステップ 7：ランタイムの注入 — 既存のインジェクターを変更せずに実行し、ユーザーが明示的に変更を求めない限り、注入された動作／結果を維持します。
8. ステップ 8：プレビュー、自律的な概要 QA 修正、必須のユーザー修正待ち、修正メモに基づく修正、ユーザー確認、納品 — 必ず scripts/serve.py でスキルのプレビューサーバーを起動し、ランタイム QA キャプチャ URL を開き、初回修正のための Playwright QA 概要ロングショットを 1 回撮影した後、ユーザーがスライドの修正箇所を指定できるように停止します。保存された修正メモに基づく修正後は、スクリーンショットによる検証パスを実行せず、メモを修正済みとしてマークし、ユーザー確認待ちにしてください。 絶対遵守の納品ルール： デッキを生成または更新した後は、$PYTHON_BIN "$SKILL_DIR/scripts/serve.py" {topic}/index.html が実行され、プレビュー URL をユーザーに伝えるまで完了してはいけません。HTML ファイルを直接開くだけでは不十分です。編集モード、保存、画像の置き換え、終了／シャットダウンの各コントロールには、Magic Slide プレビューサーバーが必要です。スキルサーバーの代わりに python3 -m http.server、npx serve、またはファイル URL を使ってはいけません。

絶対遵守の QA ゲート： 新しく生成したデッキで serve.py を実行した後、?ms_qa=overview&ms_qa_capture=1 を開き、QA ウォールに iframe の読み込み完了が表示されるまで待ち、Playwright でページ全体／スクロール QA 概要のロングショットを 1 枚撮影し、最も目立つ表示上の問題をスライド番号順に修正してください。この自律的な初回確認では、概要の修正後にスライド単体のフルサイズスクリーンショットを撮影しないでください。詳細なトリアージ順序と Playwright のみを使うスクリーンショットのルールについては、references/workflows/step-10-preview.md に従ってください。その後、QA Overview を再度開くか、そのまま表示した状態にして停止してください。ユーザーに、QA カードの Revise slide でスライドの変更箇所を指定し、準備ができたら戻るよう伝えてください。最終 QA や納品の前に、ユーザーによるこの修正確認の保留を必ず挟んでください。修正を続ける場合は、まず {topic}/sources/qa/visual-issues.json の未解決の記録を読み込んでください。

絶対遵守の更新ルール： デッキを生成した後、ユーザーがチャットで変更を依頼した場合は、まず {topic}/sources/qa/visual-issues.json を読み込み、未解決の修正依頼があれば優先してください。未解決の記録がある場合は、保存済みの JSON と対応する {topic}/sources/slide-XX.html および {topic}/sources/style.css に基づいて修正してください。スクリーンショットを使うのは、JSON／ソースのコンテキストから解釈するには曖昧すぎる記録に限り、Playwright で撮影してください。まずモジュール化されたソースファイルを編集し、その後 merge-slides.py を再実行し、既存の inject-runtime.py を変更せずに再実行してください。修正した JSON レコードは status: "fixed_pending_confirmation"、resolved: false に設定し、Magic Slide プレビューサーバーを更新または再起動して、ユーザーが確認または追加の変更依頼をできるよう、QA Overview を開いたままにしてください。ユーザーから明示的に視覚的な確認を求められない限り、保存済みの JSON 記録を修正した後にスクリーンショットによる検証を実行しないでください。ユーザーから明示的に結合済み HTML の修正を求められた場合、またはブラウザー編集モードの保存フローから変更する場合を除き、エージェントによるフォローアップ変更で {topic}/index.html を直接編集しないでください。

Brief Lite は必須です。 汎用的または不安をあおるテンプレートの出力を防ぐ品質ガードレールとして機能します。簡潔にしてください。ユーザーが、手間をかけたデザインの検討、リスクの高いビジュアルの方向性、またはデッキ全体を生成する前の小規模なサンプルを求めた場合に限り、時間のかかるプロトタイプのゲートを使用してください。

詳細なワークフロー手順

各手順の詳しい説明は、references/workflows/ ディレクトリにあります。その手順に進んだら、該当するファイルを読んでください。

• Step 1: Gather Requirements - 質問グループ4つ（トピック／対象読者の視点、スタイル、言語（必須）、画像）をすべて必ず尋ねてください。言語に関する質問は決して省略しないでください。
• Step 2: Web Search - 最新情報をオンラインで検索する場合は任意で実施します
• Step 3: Generate Outline - プレゼンテーションの構成を作成して確認します
• Step 4: Write Brief Lite - コーディング前に必要なデザインブリーフを簡潔に作成します
• Step 5: Generate Production Sources - 確認済みのアウトラインとBrief Liteに基づいて、style.cssとすべてのスライドを直接作成します
• Step 6: Merge Slides - モジュール化されたソースを単一のHTMLに統合します
• Step 7: Inject Runtime - 既存のインジェクターを実行し、明示的な依頼がない限り、注入された動作／結果を維持します
• Step 8: Preview & Final QA - プレビューを起動し、品質を確認します

従来の任意のワークフローファイル：

• 任意：ビジュアルプロトタイプの作成 - ユーザーが最初にサンプルを希望した場合のみ使用します
• 任意：ビジュアルゲートの通過 - 任意のプロトタイプワークフローでのみ使用します

生成後の編集

ユーザーは2つの方法でプレゼンテーションを編集できますが、エージェントによる編集では、必ず正本となるファイルを維持してください。

編集にはプレビューサーバーが必要です。 編集モードについて説明する前に、scripts/serve.pyを通じてデッキが配信されていることを確認し、サーバーのURLをユーザーに伝えてください。サーバーが起動していない場合は、先に起動してください。

キーボード操作の範囲。 デッキをローカルのserve.pyプレビュールート（http://localhost:.../deck/...）から開いた場合、すべてのランタイムショートカットを使用できます。同じHTMLをこのローカルプレビューのコンテキスト外で開いた場合は、プレゼンテーション用の安全なショートカットのみが有効です：概要表示のO、カーソル表示のC、スライド移動のSpace／矢印キー。

発表者ページインジケーター。 発表者ウィンドウには、コントラストの高い現在ページ／総ページ数のインジケーターを下部のコンソールに常時表示し、ナビゲーション操作のたびに更新してください。このインジケーターは発表者シェル内にのみ作成し、聴衆向けのスライドキャンバスや、エクスポートしたスライドのビジュアルには絶対に複製しないでください。

1. モジュール化されたソースを編集する（エージェントが行うすべての変更の既定）：

• {topic}/sources/slide-XX.htmlまたはstyle.cssを編集します
• mergeスクリプトとinjectスクリプトを再実行します
• ブラウザーを更新します

2. 統合済みHTMLを編集する（明示的な簡易修正、またはブラウザー編集モードの場合のみ）：

• ブラウザーで「e」を押して編集モードに入ります
• テキストをクリックしてインライン編集します
• 「Save」をクリックして変更をindex.htmlに書き込みます
• プレビューサーバーは、ブラウザーで保存された変更をsources/に同期しようとします
• ブラウザーのSaveフローを使わずにindex.htmlを直接編集する場合は、モジュール化されたソースが古くなる可能性があることを警告し、代わりにsources/を使うよう案内してください

ファイル構造

{topic}/
├── index.html          # Final merged presentation (deliverable)
├── assets/             # Final presentation assets (if generated)
│   ├── image-1.png
│   └── ...
└── sources/            # Process files and modular source files
    ├── outline.md      # Confirmed outline
    ├── create_sources.mjs  # Optional generation helper, if used
    ├── qa/             # QA screenshots/reports, if generated
    ├── style.css
    ├── slide-01.html
    ├── slide-02.html
    └── ...

トピックのルートディレクトリは整理された状態に保ってください。index.html、assets/、sources/以外のすべての作業ファイルは、{topic}/sources/内に置いてください。

主要な参照ファイル

生成中は必要に応じて、以下のファイルを参照してください。それぞれのトピックについて唯一の信頼できる情報源として扱い、このファイルやワークフローの手順でルールを長々と再構成しないでください。

• design-system.md — 美的な方向性とテンプレート化を防ぐためのガードレール
• generation-guide.md — 制作計画と生成戦略
• layout-guide.md — レイアウトの基本要素、スライドへの適合、はみ出し、垂直方向のバランス、出典注記の配置
• html-contract.md — 必須のスライド構造、デッキのトーンモード、ルート背景、SVG の仕様、ファイル命名、検証チェックリスト
• flip-engine.md — Magic Move / data-magic-id の計画と信頼性に関するルール
• images.md — 生成画像の使用、アップロード可能なラッパー、表紙画像の方針

デザイン哲学

1. アウトラインはトピック一覧ではなく、論旨でなければなりません — すべてのスライドが単に「これも存在する」と示すのではなく、主張を前進させます
2. まず Brief Lite — CSS を書く前に、トピックに合ったビジュアル世界と基本となる明暗のトーンを決めます。簡潔にまとめつつ、デザインの狙いが伝わるように出力してください。
3. Magic Move は早い段階で計画します — HTML ができる前に、アウトラインでコンテンツの受け渡しの機会を作ります。概要／詳細、指標／ヒーロー統計、地図／ズーム、比較／事例、その他の主要なアンカーを含めます。後から装飾的な重複を追加して動きを作るのは避けてください。
4. 一度生成して確認したら、いったん停止します — アウトラインと Brief Lite の作成後、デッキ全体を生成します。Playwright QA の概要で明らかな遠景表示の問題を修正したら、必須のユーザーによる Revise slide マーキングの工程に進むまで停止し、最終版の納品を待ちます。
5. QA 概要は診断ではなく、視覚確認のためのものです — 概要は、レンダリングされたスライドを一覧し、人間／エージェントが目視確認して修正メモを記録するための画面として使います。個別のチェックは、構文、プレビューの起動、実行時の操作、Playwright でレンダリングしたスクリーンショットの確認に限定してください。
6. 表紙は特別な場面です — スライド 1 は、簡潔な表紙コピーを備えた独自のオープニング構成にします。製品／AI／インフラのデッキでは、読み取れるプロセス図を載せず、タイトルを主役にしてください。表紙の詳細なルールについては、design-system.md、images.md、html-contract.md を参照してください。
7. すばやく反復します — 問題があれば、CSS と影響を受けるソーススライドをすばやく修正し、再度マージ／注入します。
8. マージ済み HTML は生成物です — {topic}/index.html は生成された出力として扱います。HTML を直接編集するのは、明示的な一度限りのパッチ、またはブラウザーの編集モードでの Save フローに限ります。
9. レイアウトの信頼性は必須です — 基本要素、スライドへの適合、はみ出し、垂直方向のバランス、出典注記の配置については、layout-guide.md に従ってください。
10. 人工的なスライド装飾や Magic 専用ラベルは使いません — html-contract.md と flip-engine.md に従い、ブラウザーのバーのような上部帯、全幅のブランドピル、Magic Move の連続性を作ることが主な目的の本文トークン列は生成しないでください。

品質基準： どのデッキにも、独自性と意図が感じられるようにしてください。最初に思いついたもののように見えてはなりません。別のトピックにもデザインを変えずに使い回せるなら、そのデザインは汎用的すぎます。

可読性の基準： 読めないテキストは好みの問題ではなく、デッキの欠陥として扱ってください。テキストのコントラストと収まりに関する詳細なルールについては、html-contract.md、layout-guide.md、design-system.md を参照してください。

出力品質

すべてのプレゼンテーションは、次の条件を満たす必要があります。

• 自己完結型 — 外部依存のない単一の HTML ファイル
• 滑らか — Magic Move が流れるようなトランジションを作成
• ポータブル — オフラインで動作し、簡単に共有できる
• 編集可能 — 反復しやすいモジュール化されたソース
• 独自性がある — 汎用的な AI の美学ではない、独自のビジュアルスタイル

目指すのは、センスを保ちながらスピードを上げることです。ビジュアル世界を決め、早い段階でプレビューを確認してからすばやく生成し、レンダリングされたデッキを見ながら反復してください。