bowen31337/image-to-editable-ppt

Image to Editable PPT (Claude Code 移植版)

同梱の editppt ランタイムを使用して、視覚的なスライドを編集可能な .pptx に分解、再構築、検証、および組み立てます。入力は、1つ以上の画像、PDF、または画像ベースのPPT/PPTXです。出力は常に1つの .pptx で、入力ページごとに1スライド、入力順に配置されます。

<skill-root> は、この SKILL.md を含むディレクトリを指します。

このスキルの構成

このファイルは、あなた（オーケストレーター）によって読み込まれます。ページレベルの作業は、ページ再構築エージェント（バックグラウンドサブエージェント、または単一ページの場合はあなた自身）が生成されたプロンプトに従って実行します。各ルールには1つの信頼できる参照元があります。推測せずにポインタに従ってください。

• prompts/page-worker.md — ページ再構築エージェントのテンプレート：所有権の境界、読み取り手順、実行順序、必要な出力、戻り値の形式。scripts/build-page-worker-prompt.py によって入力されます。
• references/cli-helper.md — editppt のインストール確認、コマンドツリー、構文。コマンドを選択するときに読みます。
• references/manifest-schema.md — すべての実行/ページアーティファクトのJSON契約。実行またはページファイルを書き込む、または検証するときに読みます。
• references/page-decision-tree.md — 背景、画像アセット、ネイティブテキスト/図形/テーブルへの変換、テキストヒントの使用法、最終セルフチェック、修正と警告の判断基準。ページ再構築エージェントがこれを読みます。あなたが読む必要はほとんどありません。

Claude Code ランタイムマッピング

元のスキルはCodexを対象としています。以下は、これをClaude Codeで動作させるための置き換えです。参照元でCodex相当の概念が言及されている場合、ここに記述された置き換えが適用されます。

元の (Codex) 概念	Claude Code での対応
組み込み image_gen.imagegen + 画像モデルアセットシート	claude-native バックエンドに置き換えられます。 Claudeはビットマップを認識できますが生成できないため、アイコン/イラストをSVGとしてトレースし、写真は長方形のソース領域として保持し、クリーンベースをローカルでインペイントします (references/page-decision-tree.md セクション2.4)。常に --image-backend claude-native を指定して prepare を実行してください。builtin-imagegen は使用しないでください。
CLIイメージAPI (editppt image generate/edit)	オプションのアップグレードとしてのみ使用され、editppt doctor --check-api が準備完了のバックエンドを報告し、かつオブジェクトがネイティブソースに適合しない場合にのみ使用します。必須ではありません。
view_image	Read ツールで画像ファイルパスを読み取ります (source.png、text_hints.png、拡大画像と .compare.png 画像、preview.png、split_assets_contact.png)。
ページワーカー/サブエージェントの起動	Agent ツール、subagent_type: "general-purpose"、run_in_background: true、name: "ppt-<page_id>" (例: ppt-page_003) を使用します。
--agent-id のワーカーID	エージェントに指定した名前と同じ (ppt-page_003)。シングルページのローカルモードでは main。
ワーカーの待機	バックグラウンドエージェントは終了時に通知します。ループでポーリングしないでください。
ワーカーへの修正送信	ワーカーの名前に SendMessage を送信します。これにより、ワーカーはコンテキストを保持できます。
サンドボックス / ネットワーク承認	Claude Code の権限プロンプト。ローカルのRapidOCRヒントを使用するclaude-native実行では、外部呼び出しは一切発生しません。PaddleOCRは、トークンが設定されている場合にのみ呼び出されます (editppt prepare / editppt run hints)。オプションのアップグレードが使用される場合、editppt image generate/edit も外部呼び出しを行います。

エントリー契約

これらのオーケストレーターレベルのルールは、ここで一度だけ定義されます。

• CLIが最優先。 editppt は必須のランタイムです。editppt --help が失敗した場合は、<skill-root>/cli から references/cli-helper.md の事前実行チェックに従ってインストールしてください (uv が存在する場合は uv tool install --force --editable <skill-root>/cli を優先し、次に pipx、最後に pip --user を試します)。その後、editppt doctor を実行します。
• CLIを介してのみ状態を管理する。 editppt prepare <input...> で開始します。その後、すべての状態遷移は editppt コマンドのみを使用して進めてください。実行/ページ状態JSONを手動で書き込まないでください。これにより、実行が決定論的で再開可能になります。
• 誰がページを再構築するか。 ページが1つだけの実行は、editppt run dispatch --local がそれを要求した後、ローカルモードであなたが再構築します。マルチページの実行は、バックグラウンドのページワーカー（ページごとに1つ）によって再構築されます。マルチページのアーティファクトを自分で再構築しないでください。各ページは多くのコンテキスト（画像、マニフェスト、修正ループ）を消費し、それらを個別のワーカーに保持することで、オーケストレーションのコンテキストを使いやすく保ち、ページを並行して実行できるようになります。
• アーティファクトの所有権。 シングルページのローカルモードで --local が要求された後を除き、manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json、page_result.json を書き込まないでください。ローカルモードは、ワーカーと同じページプロンプト、参照、出力、run record 検証に従います。
• 画像バックエンド。 以下の「Claude Code での画像バックエンド」を参照してください。許可されたソースがオブジェクトを再現できない場合、ページは検証に失敗します。形状やアイコンを近似的に切り取って代用することはしません (references/page-decision-tree.md セクション2)。
• 許可される外部呼び出し。 スライドを編集可能なPPTに変換するリクエストは、その変換に必要なOCR呼び出し（および設定されている場合は画像API呼び出し）を許可します。ただし、ユーザーがローカルのみの処理を要求した場合、または入力を機密とマークした場合は除きます。タスクローカルのページ画像、プロンプト、マスク、参照画像のみを送信し、無関係なファイルや資格情報は送信しないでください。サードパーティのエンドポイントは、ユーザーが設定または名前を指定した場合にのみ許可されます。
• 自律性。 ルーチン的な再構築、設定済みのフォールバック、およびページローカルの修正は、確認ゲートなしで実行します。ユーザーが提供できるもの（OCRトークンの決定、不足している入力）についてのみ、ユーザーに確認を求め停止します。ユーザーにデバッグを依頼する代わりに、具体的なブロッカーを報告します。
• オブジェクト決定 は references/page-decision-tree.md に従います。決定論的な検証は構造上のゲートであり、オブジェクトソースの決定を放棄することはありません。
• manifest.json は信頼できるページビルドソースです。run record は page.pptx をマニフェストに対して検証し、run finalize は記録されたマニフェストからデッキを再構築します。

資格情報の取り扱い

シークレット（PaddleOCRトークン、オプションの画像APIキー）は、ユーザーがチャットに貼り付けるとトランスクリプトに残ります。ユーザーに、値がCLIに直接渡されるように、! プレフィックスを使用して自分で設定コマンドを実行するよう提案してください。例：

! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1   # オプションの画像APIアップグレード

ユーザーがキーをチャットに貼り付けた場合は、editppt config で保存し、決してエコーバックしないでください。CLIは出力でマスクします。プロジェクト、実行ディレクトリ、またはスキルディレクトリにキーを書き込まないでください。

Claude Code での画像バックエンド

Claudeは視覚認識能力を持っていますが、画像生成はできません。そのため、すべての実行で claude-native バックエンドを使用します：editppt prepare <input...> --image-backend claude-native。その後、ページ再構築エージェントは references/page-decision-tree.md セクション2.4に従って、各オブジェクトのソースを選択します。

• アイコン、ロゴ、バッジ、手描きのマーク、フラットなイラスト — ClaudeはこれらをSVGとしてトレースします (editppt image zoom、次に editppt image svg)。PPTXには実際のSVGが埋め込まれるため、PowerPointでユーザーは色を変更したり、「図形に変換」を使用して個々のパスを編集したりできます。これにより、元のスキルのビットマップアセットよりも、これらのオブジェクトの編集がより容易になります。
• 写真、スクリーンショット、テクスチャブロック — 長方形のソース領域として保持されます (editppt image photo-region)。ベクトルトレースすると、漫画のようになってしまいます。
• 再構築されたテキストの背後にある複雑な背景 — ローカルインペインティングでクリーン化されます (editppt image inpaint)。

ユーザーに画像APIについて尋ねないでください。editppt doctor --check-api がたまたま準備完了のバックエンド（Codexログインまたは設定済みキー）を示した場合、ワーカーは、複雑な背景上の写真の切り抜きなど、ネイティブソースにうまく適合しないオブジェクトに対して、オプションのアップグレードとして editppt image generate/edit を使用することがあります。ページ内のアセットコマンドは直列に実行されます。

ワークフロー

フェーズ1: 準備

references/cli-helper.md の準備の例と、references/manifest-schema.md の実行/ページファイルの説明を読んでください。

editppt prepare <input...> --image-backend claude-native

デフォルトの --out-root を維持してください。これにより、カレントディレクトリの下に作業用実行ディレクトリ output/image-to-editable-ppt/<job-id>/ が作成されます。ユーザーが結果を望むフォルダを指定しないでください。そのフォルダには最終デッキのみが配置されるべきです（フェーズ4）。この後、deck_manifest.json、page_jobs.json、notes_manifest.json があり、各ページに source.png と page_request.json が存在する必要があります。

Prepareは、ページごとのテキストヒント (text_hints.json/text_hints.png) も書き込みます。トークンがない場合、これらはローカルのRapidOCRから取得され、テキストをデバイス上で読み取り、アップロードは発生しません。そのため、ユーザーに何も要求しないでください。Prepareがジオメトリのみの builtin-ink バックエンド（RapidOCRが利用不可）を報告した場合にのみ、ページをディスパッチする前に一度だけユーザーに尋ねてください。https://aistudio.baidu.com/account/accessToken からの無料トークンを editppt config --paddle-ocr-token <token> で保存すると、ヒントがコンテンツを認識するようになり（テキストの位置を測定するだけでなく、実際に読み取る）、テキストの忠実度が著しく向上します。editppt run hints <run> で現在の実行のヒントをその場で再生成します。無料の個人用クォータは、このスキルには十分すぎるほどです。ユーザーの選択を待ちます。ユーザーが拒否した場合は、オフラインヒントで続行し、再度尋ねないでください。

ユーザーがIndra OCR（またはより高速な/代替のローカルOCR）を要求した場合は、editppt config --text-hints-backend indra を実行し、[indra] エクストラを使用してCLIを再インストールします (references/cli-helper.md)。Indraのモデル重みには、商用利用を制限する修正OpenRAIL-Mライセンスが適用されることを一度だけ通知してください。テストでは、RapidOCRの方がスライドテキストをより完全に読み取ったため、独自の判断で切り替えないでください。

トークンが設定されているが、権限プロンプトやネットワーク障害のためにOCRがフォールバックした場合、それは望ましい品質パスではありません。呼び出しを許可し、ページ再構築の前に editppt run hints <run> を再実行してください。ユーザーがOCRを拒否した場合、許可されたOCR試行が実際のサービス上の理由で失敗した場合、またはユーザーがローカルのみの処理を要求した場合にのみ、オフラインで続行します。

フェーズ2: ページの再構築またはディスパッチ

繰り返し呼び出し、返された stage に応じて行動します：

editppt run next <run> --json

stage=rebuild_page_locally（正確に1ページ）。それを要求し、自分で再構築します：

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.md
2. editppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --local
3. 生成されたプロンプトを Read ツールで読み取り、そのページディレクトリ内でそれに従い、ワーカーが生成するのと同じ出力を生成します。

stage=dispatch_pages。提案された各ページについて、この順序で：

1. 上記のスクリプトを使用してプロンプトをビルドします。
2. Agent ツールでワーカーを起動します — subagent_type: "general-purpose"、run_in_background: true、name: "ppt-<page_id>"、description: "Rebuild <page_id> as editable PPT"、そして prompt は次のように設定します：

   You are a page reconstructor for the image-to-editable-ppt skill (Claude Code port).
   Read <abs-run-dir>/pages/<page_id>/worker-prompt.md and follow it exactly.
   Claude Code notes: view images with the Read tool; you cannot generate
   bitmaps, so non-text visuals come from page-decision-tree.md section 2.4
   (SVG traces, photo regions, local inpaint); run shell commands with Bash.
   Do not touch files outside your page directory.
   

3. 起動が成功した場合のみ：editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md

1つのメッセージでバッチのすべての提案されたページを起動し、並行して実行できるようにします。--out と --prompt-file は絶対パスにする必要があります。そうしないと、ページディレクトリが2回前置される可能性があります。同時実行スロットは page_jobs.json.max_concurrent_pages から取得されます（デフォルト6）。

stage=wait。ディスパッチされたページはアクティブなリースであり、アイドルスロットではありません。完了通知を待ちます。ワーカーが遅い、または無音だからといって、停止、リセット、または置き換えないでください。複雑なページは正当に10分以上かかることがあります。

stage=configure_backend。提案された builtin-imagegen/CLI契約ではなく、editppt run backend <run> --mode claude-native を実行します。

フェーズ3: 記録

ワーカーの完了通知が到着したら（またはローカルページを完了したら）：

editppt run record <run> --page <page_id> --agent-id <id>

これにより、page.pptx が manifest.json に対して検証され、配置されたオブジェクトにソースピクセル座標がない場合、マニフェストがページを独立して再構築できない場合、または validation.json にトップレベルの passed: true がない場合、ページは拒否されます。その後、editppt run next に戻ります。

修正。 Recordが失敗した場合、失敗の証拠を読み取り、ページの所有者に影響を受けるアーティファクトのみを修正させ、再検証させ (editppt page validate、references/cli-helper.md を参照)、再度記録します。マルチページモードでは、新しいワーカーを起動するのではなく、既存のワーカー (ppt-<page_id>) に証拠を SendMessage します。既存のワーカーはすでにページコンテキストと検証済みアセットを保持しています。無関係なマニフェストエラーやテーブルエラーを修正するために、準拠しているアセットを再生成しないでください。

リセット は、ページが新しい実行を必要とする場合にのみ行います。ワーカーが終了状態で終了した、ユーザーがキャンセルした、または繰り返し到達可能性を試みてもページローカルの進捗が見られない場合です。遅いことは失われたこととは異なります。ブロッカーを修正した後：

editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost

リセットにより、ページは pending 状態に戻ります。新しいプロンプトとワーカーでフェーズ2を再開します。既存のアーティファクトは、来歴と選択的な再利用のために保持されます。

入力または条件を変更した後にのみ再試行してください。同一の失敗する呼び出しを繰り返さないでください。実際の前提条件が欠けている場合は、進捗を保持し、具体的なブロッカーを報告してください。出力がチェックに合格したら、先に進みます。変更されていないビジュアルQAを繰り返さないでください。

フェーズ4: 最終化

run next が最終化ステージを返したら：

editppt run finalize <run>

Finalizeは、各記録された pages/page_NNN/manifest.json からページ順にデッキを再構築し、.pptx のスピーカーノートを変更せずにコピーし、結果を検証します：有効なパッケージ、スライド数 = 入力ページ数、正しいPDF/PPTXページネーション。その後、最終デッキをカレントディレクトリにコピーします。実行ディレクトリはそのまま残ります。

---

アーティファクトの所有権（再確認）。record を実行したエージェント（ローカルの場合は main、またはワーカーエージェント）のみが、ページディレクトリ内のアーティファクトを検証または変更できます。

---

翻訳に関する注記（削除予定）：

• 技術用語とコマンドは元の言語のまま維持しつつ、プロンプトと手順は日本語の技術翻訳者として（Claude Code、Cursor、Codex、CopilotなどのAIエージェントスキルに合わせた）自然な日本語で表現しました。
• 元のマークダウン構造とコードブロックは保持されています。