Communitygithub.com

Hasasasa/html-to-editable-pptx

HTMLスライドデッキを真に編集可能なPPT / .pptxに変換します。テキストはPowerPointネイティブのテキストボックスとして保持され、スクリーンショットにはなりません。エージェントスキル(Claude Code / Cursor / Codex / opencode)+ プレーンPython CLI。

html-to-editable-pptx とは?

このスキルは、HTMLで作成されたスライドデッキを、完全に編集可能なPowerPoint (.pptx) ファイルに変換するためのものです。変換されたPPT内のテキストは、画像ではなくネイティブなテキストボックスとして保持されるため、PowerPoint上で直接編集や書式変更が可能です。主な用途は、WebブラウザやHTMLベースのプレゼンテーションツールで作成したスライドを、同僚やクライアントに配布可能なPPTファイルに変換することです。対応プラットフォームはClaude Code、Cursor、Codex、opencodeなどのAIエージェントツールと、Python CLIです。スキルは、HTMLの解析、レイアウト計測、PowerPoint形式へのアセンブル、フォントの埋め込み(Google Fontsからの自動取得とサブセット化を含む)、構造化チェック、そして視覚的な監査(要PowerPoint COMまたはLibreOffice)という一連のパイプラインで動作します。特に、中国語・日本語・韓国語(CJK)文字を含むHTMLに対しては、Noto Sans SCとNoto Serif SCが自動で埋め込まれます。変換は元のHTMLファイルを変更せず、監査で見つかった問題はコピーされた`audited.html`に修正が適用され、その修正版が変換の入力として再利用されます。視覚的な監査モード(triage / page / manual)やフォントの自動インストール設定は、ユーザー設定ファイル(`.config.local.toml`)で管理され、初回使用時にエージェントがユーザーに問い合わせて設定します。

対応✓Claude Code✓Codex CLI✓Cursor✓OpenCode
npx skills add Hasasasa/html-to-editable-pptx

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

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

ドキュメント

html-to-pptx

いつトリガーされるか

ユーザーが以下のいずれかの意図を発した場合:

  • 「このHTML / ウェブデッキをPPT / pptxに変換して」
  • 「HTMLでスライドを作ったので、同僚にpptを渡したい」
  • 「報告会でブラウザを開くのが不便なので、pptファイルが欲しい」
  • HTMLファイルのパスが既にあり、ppt / pptx / プレゼンテーション / スライドに言及している

呼び出し方

<skill_dir> はこのスキルのインストールパスです(通常 ~/.claude/skills/html-to-pptx/、Windowsでは %USERPROFILE%\.claude\skills\html-to-pptx\)。以下のコマンド内の <skill_dir> を実際のパスに置き換えるか、先に cd <skill_dir> してから python convert.py ... を直接実行してください。

python <skill_dir>/convert.py <input.html>
  • デフォルトでは、入力ファイルと同じディレクトリに <input>.pptx が出力されます
  • フォントは完全にオンデマンド:HTMLで使用されているフォントは変換時にGoogle Fontsから取得され、サブセット化されて埋め込まれます。キャッシュは %LOCALAPPDATA%\html-to-pptx\fonts\ または ~/.cache/html-to-pptx/fonts/ に保存され、次回同じフォント名の場合は即座に再利用されます
  • HTMLにCJK文字が含まれる場合、自動的にNoto Sans SC + Noto Serif SCがシードされます(初回のみ約40 MB / 約30秒でダウンロードされ、Static Regular/Boldがインスタンス化され、以降はキャッシュがヒットします)
  • Google Fontsにないフォントファミリーは、ビューアのシステムフォントにフォールバックされ、警告が出力されます
オプション意味
--out <path>出力 .pptx のパスをカスタマイズ
--keep-screenshots各ページのHTML参照スクリーンショットと preflight.json を同時に保持
--no-embed-fontsフォントの埋め込みをスキップ。ファイルサイズは小さくなりますが、別の環境ではシステムフォントにフォールバックします
--no-preflightStage 1のリスク事前スキャンを無効化
--no-verifyStage 5aの構造化セルフチェックを無効化
--no-visual-auditStage 5bのビジュアル監査成果物の生成を無効化。通常はオフにしないでください
--install-user-fonts自動検出された非CJKフォントをユーザーフォントディレクトリにインストールします(WPSで正しくレンダリングされるようにするため)。Win/macOS/Linuxすべてに対応。事前にユーザーに確認が必要です。下記「設定確認」セクションを参照
--only-slides N,N,N増分再実行。カンマ区切りのページ番号(1ベース)。計測は指定ページと前回のキャッシュ結果をマージして実行、アセンブル/埋め込みは全量実行、Stage 5aは指定ページのみレンダリング、Stage 5bは指定ページの比較画像のみ再構築。その他のページはすべて前回のキャッシュを再利用。監査イテレーション専用。詳細は下記「増分再実行」セクションを参照
--cleanup変換は行わない。input.pptx の隣にある audit / measurement / preflight の作業ファイルを削除し、.pptx と audited.html のみを残します。最終納品前に使用。下記「ワークフロー」の最終ステップを参照

作業コピー(元のHTMLは変更しない)

初回 python convert.py <input>.html の実行が完了すると、convert.py は自動的に <input>.audited.html を元のHTMLと同じディレクトリにコピーします。仕組み:

  • すべての監査修正は audited.html に適用され、元のHTMLは変更されません
  • 以降のconvert実行(--only-slides を含む)では、入力として <input>.audited.html が使用され、出力は依然として <input>.pptx です(自動的に .audited サフィックスは除去されます)
  • audited.html が既に存在する場合 → 再利用され、上書きされません(前回の修正が保持されます)
  • エージェントが誤って元のHTMLを入力として渡した場合 → convert.py が内部で検出し、audited.html に自動で切り替えます
  • cleanup は audited.html を削除しません(納品可能な副産物として扱い、.pptx と一緒に納品します)
  • 最初からやり直したい場合 → audited.html を手動で削除してから再実行してください

設定(.config.local.toml)

スキルのルートディレクトリにあるオプションのローカル設定ファイルで、gitignoreされ、ユーザーごとに存在します。現在、以下の3つの設定項目があります:

[fonts]
auto_install = "ask"   # "yes" 自動インストール、"no" 絶対にインストールしない、"ask" エージェントがユーザーに確認

[cleanup]
default = "clean"      # "clean" ワークフロー最終ステップで自動cleanup、"keep" 監査成果物を保持

[audit]
mode = "ask"           # "triage" / "page" / "manual" / "ask" エージェントがユーザーに確認
  • ファイル / キーが存在しない場合 → デフォルト値(上記と同じ)が使用されます
  • テンプレート:<skill_dir>/.config.local.toml.example
  • fonts.auto_install は convert.py によって強制的に読み取られ、適用されます(=yes は自動的に --install-user-fonts を追加、=no は自動的に無視)
  • cleanup.default はエージェントがワークフローの最終ステップで読み取り、動作を決定します
  • audit.mode はエージェントが最初のconvertの前に確認します。Stage 5b の後、この値に従ってレビューが実行されます:
    • "triage" → メインエージェント自身が audit_contact_*.png の概要を見て振り分け、その後サブエージェントを対象ページの個別画像に派遣し、トークンを節約します
    • "page" → 対象となる各ページにサブエージェントを派遣し、slide_NN_compare.png の個別画像を確認します。最も厳密なカバレッジです
    • "manual" → 監査成果物のみを生成し、ユーザーによる手動確認に委ねます。ユーザーから問題がフィードバックされた後に修正します
    • "ask" またはキーが存在しない場合 → エージェントは AskUserQuestion を通じてユーザーの好みを収集し、この項目を書き換えます(デフォルト)
  • 初回使用時:エージェントは AskUserQuestion を通じて fonts.auto_install と audit.mode を収集し、その後自らこのファイルに書き込みます。ユーザーが手動で作成する必要はありません。

設定確認(最初のconvertの前に完了させる)

最初のconvertの前に、2つの設定項目を確認する必要があります:fonts.auto_install と audit.mode。プロセスは同じで、違いはトリガー条件と質問方法のみです。

共通プロセス

各設定は、以下の順序で独立して判定されます:

  1. <skill_dir>/.config.local.toml を読み取り、対応するフィールドを確認:
    • 有効な値で ask 以外の場合 → その値に従って動作し、セッション内では再度問い合わせません
    • ask またはファイル/フィールドが存在しない場合 → 「トリガー判定 + ask」の手順に進みます
  2. CLAUDE.md / グローバル指示に同等の値が明記されている場合 → その明記された値に従い、configファイルも補足的に書き込みます(単一の事実源を維持するため)

トリガー後、AskUserQuestion で一度だけ質問します。両方の設定に対して行う必要があります:

  • ユーザーの回答を <skill_dir>/.config.local.toml の対応するフィールドに書き込みます(ask は書き込みません。そうしないと次回のセッションでも再度質問されます)
  • 現在のセッションでは、その回答に従って動作します

configファイルへの書き込み時:ファイルが存在しない場合 → ファイル全体をWriteで書き込みます([fonts] [cleanup] [audit] の3つのセクションのテンプレート)。ファイルが既に存在する場合 → Editを使用して単一行を置き換えます(このフィールドのみを変更)。Writeでファイル全体を上書きしないでください。そうすると、ユーザーが追加した他のカスタムキーが失われます。

同じセッションで両方の設定がトリガーされた場合 → 1つのAskUserQuestionにまとめて一度に質問します。

fonts.auto_install — フォントのインストール

PowerPoint COMの slide.Export() とWPS Officeは、どちらもpptxに埋め込まれた生のTTFを読み取りません。監査レンダリングとWPSはどちらもシステムフォントにフォールバックします。ユーザーフォントディレクトリにインストールすると、両方ともシステムフォントとして使用されるようになります。ディレクトリ(いずれもユーザーレベルで、手動で削除可能):

  • Windows: %LOCALAPPDATA%\Microsoft\Windows\Fonts\ + HKCUレジストリ
  • macOS: ~/Library/Fonts/
  • Linux: ~/.local/share/fonts/ + fc-cache -f

トリガー判定:HTMLの <head> にある <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / <style> 内の font-family: に登場するフォント名を確認します:

  • トリガー:任意のGF / 自家ホストフォント(Bricolage Grotesque、DM Sans、Inter、Space Grotesk、Caveat など)
  • トリガーしない:システムフォントのホワイトリスト(Arial、Times New Roman、Helvetica、Helvetica Neue、Courier、system-ui、-apple-system、BlinkMacSystemFont、SF Pro、Microsoft YaHei、SimSun、PingFang、Hiragino)のみを使用する場合

回答に従って:同意 → --install-user-fonts を追加;拒否 → 追加しない。

audit.mode — ビジュアル監査モード

3つのモード triage / page / manual(意味は上記「設定」セクションを参照)。各セッションの最初のconvertの前に必ず判定されます(HTMLの内容には依存しません)。AskUserQuestionは単一選択式で、オプションは3つのモードです。

ワークフロー(必須)

convert.py が完了しただけでは、まだ納品は完了していません。完全なプロセス:

convert.py(初回は自動的に <input>.audited.html をコピーし、すべての修正はこのコピーに適用される)
  → Stage 5a 構造化セルフチェック(OOXMLスキャン、ヒントを提供)
  → Stage 5b ビジュアル監査成果物 — PowerPoint COM または LibreOffice レンダラーが必要
  → `audit.mode` を読み取り、レビュー方法を決定:triage / page / manual
  → 【エージェント監査】
        triage モード:メインエージェントがコンタクトシートを読み取り振り分け → サブエージェントが対象ページの個別画像を確認 → 統合して audit_findings.md に書き込み
        page モード:全ページに対してサブエージェントが個別画像を確認 → 統合して audit_findings.md に書き込み
        manual モード:監査成果物をユーザーに渡し、ユーザーからの手動フィードバックを待つ
  → findingに従って、1項目ずつ最小限の局所的な修正を実施。対象は audited.html(下記「修正の規律」を参照)
  → 一連のfindingを修正後、`convert.py <input>.audited.html --only-slides <修正されたページ番号>` を実行し、新たに生成されたページのみを再監査(下記「増分再実行」を参照)
  → すべてのページがOK、またはLOWのみが残っている状態
  → 【HTMLのアンチパターン / 新しいOOXMLの境界に遭遇した場合】教訓を lessons-learned に蓄積。下記「HTMLの問題とOOXMLの境界の蓄積」を参照
  → `<skill_dir>/.config.local.toml` の `cleanup.default` を読み取り:
        "clean"(デフォルト)→ 直接 `python convert.py <out>.pptx --cleanup` を実行。ユーザーには確認しない
                          ディレクトリ内の残りファイル:<input>.html(元のまま、未変更)+ <input>.audited.html(修正版)+ <out>.pptx
        "keep"        → cleanupをスキップ。監査成果物をすべて保持
  → .pptx のパスをユーザーに納品(audited.html は修正版HTMLとして一緒に納品)

ベクター優先の原則(必須)

PPTのネイティブなtext / shape / lineで表現できるコンテンツは、編集可能な状態を優先して保持します。通常の背景色、通常の四辺枠、単線、単純な矩形/楕円、単純な ::before / ::after のワイヤーフレームは、すべてPPTのshapeで表現する必要があります。

deco_snapshot は、OOXMLで表現が難しい装飾に対してのみ使用されます(ヒット条件 + 完全な段階定義 + スクリーンショット/ベクターレイヤーの連携メカニズムについては references/supported-css.md を参照)。通常の線、グラフの軸線、単純な枠線などを一律にスクリーンショット化しないでください。これによりPPTの編集性が損なわれ、後続の局所的な修正も困難になります。

レンダラーの要件(Stage 5b の前提条件)

Stage 5b のビジュアル監査では、.pptx をPNGにレンダリングする必要があります。以下のいずれかに依存します:

  • PowerPoint COM(Windows + Office + pywin32)、または
  • LibreOffice(クロスプラットフォーム、pip install pdf2image が必要)

どちらかが利用可能であれば、監査を実行できます。convertの出力で [self-check] スキップ:利用可能な pptx レンダラーが見つかりません と表示された場合、両方ともインストールされていないことを意味します。この場合、監査は比較画像を生成せず、Stage 5b は直接スキップされます。

この場合、エージェントはユーザーに確認する必要があります(監査されていないpptxを黙って納品してはいけません):

「お使いのマシンにはPowerPointもLibreOfficeもインストールされていないため、ビジュアル監査を実行できません。PPTには目に見えない視覚的なバグが含まれている可能性があります。3つの選択肢があります:

  1. LibreOfficeをインストール(推奨、クロスプラットフォーム、2-3分):winget install LibreOffice.LibreOffice(Windows)/ brew install --cask libreoffice(mac)/ apt install libreoffice(Linux)、その後 pip install pdf2image を実行し、convertを再実行
  2. 監査をスキップして直接納品(PPTに視覚的なバグがあるリスクを受け入れる)
  3. Officeが既にインストールされている別のマシンで再実行」

ユーザーが1を選択 → インストールが完了するのを待ってからconvertを再実行;2を選択 → --no-visual-audit を付けて一度実行し、リスクを説明した上で納品;3を選択 → 現在のディレクトリとHTMLをユーザーに送信。

ビジュアル監査モード(config、前提:5bが動作している)

ビジュアルレビューを実行する前に、<skill_dir>/.config.local.toml の [audit].mode を読み取ります。通常は最初のconvertの前に、上記の「設定確認」セクションで質問が完了しているはずです。もしここでmodeがまだ "ask" の場合(エージェントが質問し忘れたことを意味します)、すぐに上記の「設定確認」セクションに従ってユーザーに質問してから続行します。

各modeの具体的な意味は上記の「設定」セクションを参照。ここでは適用シナリオのみをリストします:

mode適用
triageデフォルト、トークンを節約
page最終納品前、重要な顧客、ユーザーが最も厳密なチェックを要求する場合
manualユーザーが自分で確認したい場合

triage の役割分担は明確です:第1ラウンドのコンタクトパス = メインエージェント自身がサムネイルを見て振り分け(低コスト。コンテキストには既に元のHTML / Stage 5a / preflightが含まれています);第2ラウンドの詳細パス = 対象ページをサブエージェントに派遣して個別の比較画像を見てもらいます。サムネイルだけでHIGH/MID findingを判断してはいけません。findingを報告するには、必ず第2ラウンドのサブエージェントによる個別ページの確認を経る必要があります。

監査の振り分けと比較画像の読み取りルール

page モードでは、すべてのページがClaude Agent(...) サブエージェントに並列ディスパッチされます。triage モードでは、第2ラウンドの対象ページのみがサブエージェントに送られます。第1ラウンドのコンタクトシートはメインエージェント自身がReadし、サブエージェントは派遣されません。

メインエージェントが能動的に比較画像を読み取るシナリオは、以下の5つに限定されます:

  • triage 第1ラウンドで audit_contact_*.png の概要を読み取り振り分け
  • 対象的な修正の検証ラウンド:今回新たに生成されたページが2ページ以下で、変更がグローバルCSSに及んでいない場合 → メインエージェントが直接、新しいページの個別画像を読み取り、既知のfindingを再確認し、そのページの新たなリグレッションをスキャンします。サブエージェントは派遣しません(サブエージェントの1ラウンドは2-3分かかりますが、直接読み取りは数秒です)。新しいページがそれ以上ある場合や、グローバルな変更がある場合は、引き続きサブエージェントを使用します
  • findingの説明が曖昧で、ソースコードと矛盾し、位置を特定できない場合、対応する個別ページの slide_NN_compare.png を読み取ります
  • stickyがヒットする前に、個別ページを読み取って確認
  • ユーザーが特定のページを指摘した場合、その個別ページを読み取る

これ以外で、ページごとに比較画像をReadすることはありません。

バッチは、ウォールクロック時間を最適化するために小さく分割して並列実行します(サブエージェントが大きな画像を逐次読み取ることが遅延の主な原因です。複数の小さなバッチを並列に送信することで、1つの大きなバッチよりも2倍以上高速になります):

スライド数戦略
≤ 21 バッチ
3-201バッチあたり2ページ、すべて並列送信
> 201バッチあたり3ページ(エージェント総数を制御)

完全なサブエージェント呼び出しテンプレート + チェックリスト + findingsのフォーマットは <out>_audit/audit_prompt.md を参照。複数の Agent(..., run_in_background: true, subagent_type: "general-purpose") 呼び出しをメインエージェントの同じメッセージ内にまとめて配置することで、並列実行されます。

サブエージェントはfindingsのテキストのみを返します(pageモードでは各対象ページの ## page NN ブロック、triageの詳細バッチでは拡大確認された各ページのブロックを含む)。メインエージェントがこれらを統合して audit_findings.md に書き込みます。並列書き込みは互いに上書きし合うため、避けてください。

各findingは、安定した要素の短い名前を指定し、「HTML側の実際の状態;PPT側の差異」を説明する必要があります。PPTがHTMLに対して新たに追加または拡大した視覚的な問題のみを報告します。HTML側に既に存在する問題は、変換findingとして報告しません。

サブエージェントと並行するメインエージェントの準備(必須)

pageモードまたはtriage第2ラウンドの詳細サブエージェントを起動する際、Agent呼び出しには run_in_background: true を使用し、同じメッセージ内で同時に以下の処理を実行します:

Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
     output_mode: "content", -n: true)

各サブエージェントのプロンプトには、このバッチの slide_NN_compare.png の絶対パス、デッキHTMLのパス、lessons-learned.md のパス(適用範囲は上記「ビジュアル監査モード」セクションを参照)を直接記述する必要があります。メインエージェントのRead / Grep出力が自動的にサブエージェントに渡されることを想定しないでください。

「findingsが何であれ使用される」準備のみを送信してください。findingsを予測して事前にHTMLを変更しないでください。

修正の規律(findingに対して、根本原因を追及しない)

audit_findings.md を受け取った後、1ラウンドで今回のすべてのfindingを修正し、その後一度にconvert + auditを再実行します。1つのfindingを修正するたびに実行するわけではありません。1ラウンド = 1回のHTML編集バッチ + 1回のconvert + 1回のauditです。

findingsを受け取った後:

  • 通常は自分でcompare画像を読み取らない(findingsが既に症状を明確に説明しています)。compare画像を読み取る3つの例外は、上記「監査の振り分けと比較画像の読み取りルール」セクションを参照
  • measure.py / assemble.py / スキル内のコードを読み取って根本原因を調査しない
  • 直接 audited.html を開き、findingに従って1つずつ修正する

各findingに対して、最小限の局所的なHTML修正を行います:

  • 各findingは、「それを消す」ための1箇所だけを修正し、修正後は次のfindingに進みます(HTMLの修正を続けます。convertを再実行するわけではありません)

  • 「なぜフォントがフォールバックしたのか」「なぜレイアウトがずれたのか」という深い根本原因を追及しない

  • 「ついでに.footerも絶対配置に変更しておく」といったfindingリスト外の最適化を行わない

  • findingをまたがる構造的なリファクタリングを行わない(「すべてのスライドのfont-familyを明示的に宣言する」ことは、単一のfindingの最小修正ではありません)

  • 同じfindingが連続する2ラウンド(前回 + 今回)の両方で出現した場合 → stickyがヒットしたとみなし、ユーザーに報告します。修正範囲を拡大し続けないでください。判定キー = (ページ番号, 視覚要素の短い名前):

    • 表現 / 重要度 / HIGH↔MID の切り替えは判定をリセットしません。例:(page 5, take フォントサイズ) が round 6 で「小さい」、round 7 で「深刻に不足している」と表現された場合 → 同じstickyキーであり、round 7 でヒットします
    • 「ページ番号 + 要素」の両方が重複しない場合のみ、新しいstickyキーとみなされます
    • 隔ラウンドでの復活:round 6 で出現、round 7 で消失、round 8 で再出現した場合 → stickyとはみなされません(round 7 での不在は問題が修正されたことを意味し、round 8 は新しいリグレッションです)
    • ヒットした場合 = 今回のラウンドではそのfindingを修正せず、スキルの境界候補としてユーザーに伝えます。今回のラウンドの他のfindingは通常通り修正します

    実装:各ラウンドで audit_findings.md を統合し、Editを実行する前に、まず前回の audit_findings.md(初回ラウンドはなし)をReadして2つのラウンドをペアで比較する必要があります。今回と前回の両方に出現するキーがヒットとなります。ヒットしたfindingは別途リストにしてユーザーの判断に委ね、今回の編集キューには入れません。

今回のバッチのfindingを修正したら、一度に python convert.py <input>.audited.html --only-slides <修正されたページ番号> を実行します。

判定基準:diffの行数は、findingsの数 × 3行以下である必要があります。これを超える場合は、「余計なことをしている」ことを意味します。

増分再実行(--only-slides)

監査の第2ラウンド以降で使用します。初回ラウンドは全量実行です。

python convert.py <input>.audited.html --only-slides 2,7,12

増分は、measure / Stage 5aレンダリング / Stage 5b比較画像をカバーし、リストされたページとキャッシュが欠落しているページに対してのみ実行されます。assemble / embed_fonts は引き続き全量実行されます。audit_index.json には incremental_mode: true、fresh_indices、cached_indices、各ページの fresh: true/false が記録されます。

増分ラウンドの監査対象ページは fresh_indices のみです。page モードではこれらのページが直接振り分けられます。triage モードでは、最初にこれらのページの範囲内で振り分けが行われ、対象となったページがサブエージェントに送られます。

前提条件:前回の <out>_audit/ ディレクトリが存在すること。キャッシュが欠落している場合は自動的に全量実行にフォールバックします。HTMLのページ数が変更された場合も自動的に検出され、全量のmeasureにフォールバックします。

--only-slides を使用できない場合(視覚的な影響がリストされたページを超えて及ぶ場合、キャッシュが偽陰性となる場合):

  • グローバルCSS(<style>、ルートセレクター、.slide 共通スタイル)の変更
  • フォントの追加 / 削除(@import、font-family宣言の変更)
  • デッキレベルのトークン(背景、テーマカラー、スペーシング)の変更
  • 他のページのレイアウトに影響を与える可能性のあるグローバル変数の変更

これらのケースでは、フラグなしで全量再実行します。判断が不確かな場合 → 全量再実行が常に安全です。

HTMLの問題とOOXMLの境界の蓄積(必須)

あなたの役割は呼び出しと使用方法の蓄積であり、スキル自体の修正ではありません。スキル内部のバグを発見した場合、その場で measure.py / assemble.py を修正しないでください。

蓄積するのは以下の2つのカテゴリーのみです:

1. HTMLの書き方の問題(ユーザーのHTMLが変換の歪みを引き起こす)

カテゴリー判定行うこと
単発のケース(このデッキでのみ発生し、HTMLの1、2行を修正すれば解決する)単一ページの特殊ケースHTMLソースを直接修正;蓄積せず、報告もしない
一般的なHTMLアンチパターン(誰が同様のHTMLを書いても問題に遭遇する)デッキをまたぐHTMLを修正 + references/lessons-learned.md の「HTML記述の回避策」セクションに蓄積

2. OOXMLの表現力の境界(PowerPoint / OOXMLがネイティブにサポートしていない)

ほとんどの装飾系CSS(backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after 装飾的な使用方法 — 空のcontent + bg-image / box-shadow など)は、「カバレッジ戦略」の hasComplexDecoration によって自動的に deco_snapshot にキャプチャされます — HTMLを変更する必要はありません。::before ::after 文字列コンテンツ(content: "↑" など)はテキストチャネルを経由します。詳細は references/supported-css.md の第1段階を参照。

それでもHTMLのワークアラウンドが必要な真の境界(OOXMLのテキストレイヤーでネイティブに表現できないもの):

境界代替パス
カラー絵文字(COLR/CPALフォント)Twemoji SVG <img>、imgチャネルを経由して埋め込み
background-clip: text テキストグラデーションインライン <svg><text fill="url(#grad)">、SVGチャネルを経由

これらのカテゴリーに遭遇した場合 → HTMLを代替パスに変更 + references/lessons-learned.md の「OOXMLの境界」セクションに蓄積します。

上記の表にない新しいCSSの未サポートに遭遇した場合 → まず hasComplexDecoration が誤ってトリガーされていないか確認します(トリガー条件を1行追加するだけで解決する可能性があります)。HTMLを変更する必要はありません。詳細は references/supported-css.md の「新しいサポートを追加する標準的な手順」を参照。

スキル内のバグと思われる場合の対処方法(修正も蓄積もしない)

ある症状が、同じCSSパターンでデッキを変えても再現し、既知のOOXML境界に含まれないことを発見した場合 → これはスキルの抽象化が不十分であることを意味します。その場でスキルコードを修正しないでください。以下の2つのことを行います:

  1. 現在のデッキでは、HTML側でワークアラウンドを実施してfindingを修正し、ユーザーが納品可能なPPTを取得できるようにします
  2. 明確にユーザーに伝えます:「スキル内部の一般的なバグと思われるものを発見しました:[症状 + トリガーとなるCSSパターン + 現在のワークアラウンド]。作者にissueとして登録し、スキルのmeasure/assembleでこのパターンをより一般的に処理できるようにすることをお勧めします」

蓄積先:ローカルコピー + アップストリームテンプレート

references/lessons-learned.md はユーザーごとに独立したローカル作業コピーです(gitignoreされています)。初回の convert.py 実行時に、local_config.seed_lessons_learned() が自動的にテンプレート lessons-learned.md.example(コミット済み)からコピーを作成します。メカニズムは .config.local.toml と同じです。

  • エージェントの調査・蓄積は、すべてローカルの lessons-learned.md に対して読み書きを行います — 自由に追加/変更/整理でき、gitのノイズは発生しません
  • ローカルコピーは決してアップストリームによって上書きされません — git pull で取得されるのは .example テンプレートであり、あなたの作業コピーは変更されません
  • ある蓄積をアップストリームに戻したい場合:作者が手動でエントリを lessons-learned.md.example にコピーしてからコミットします。選択的にキュレーションされ、すべてがプッシュされるわけではありません
  • ローカルな業務 / 特定顧客専用の記述 → そのままローカルコピーに記述すればよく、アップストリームには影響しません
  • lessonsエントリには、再利用可能な症状、トリガーパターン、回避ルールのみを記述します。具体的なローカルファイル名、テンプレート名、ページ番号、顧客名、ソースコードファイル名は記述しないでください。具体的な実装箇所、コマンド、コードの詳細は、コミット / issue / メインのスキルドキュメントに残します

トリガー:一般的なHTMLアンチパターン / OOXMLの境界に遭遇した場合 → ローカルの lessons-learned.md の対応するテーブルに追加します。convertが実行されるたびに再読み取られ、即座に反映されます。

カバレッジ戦略(一言で)

スキル内部では、すべてのCSSを4つの段階に変換します:ベクターテキスト → ベクターシェイプ → ラスター装飾(deco_snapshot)→ メディア直接転送。単純なbg-color / border / border-radius は最初の2つの段階(編集可能で検索可能)を通過し、box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / 非対称角丸 / クリッピングコンテナ + 回転子要素などは hasComplexDecoration にヒットし、3番目の段階(ラスターは装飾ピクセルのみをキャプチャし、テキストは常にベクターとしてスクリーンショットの上に描画されます)を通過します。

完全な段階定義 / トリガー条件 / 新しいサポート追加ガイド(ベクター優先 → スクリーンショットフォールバック)→ references/supported-css.md。

パイプライン

[1 入力認識/事前スキャン] → [2 計測] → [3 アセンブル] → [4 フォント埋め込み] → [5a 構造化セルフチェック] → [5b ビジュアル監査]
   preflight.py    measure.py   assemble.py   embed_fonts.py  self_check.py    visual_audit.py

各ステージのアクション / 仮定に対する反論ルール / 終了アサーション / 新しいテンプレートのチェックリスト → references/methodology.md。

Stage 5b は <out>_audit/ を生成します(比較画像 + コンタクトシート + audit_index.json + audit_prompt.md)。ピクセルdiffは行いません — 数値は局所的なバグに鈍感で、誤った自信を与えます。視覚的な判断は audit.mode に従って triage / page / manual で行います。レンダラーがない場合、5bはスキップされ、上記の「レンダラーの要件」セクションに従ってユーザーに確認します。

呼び出し前

…

[翻訳はここで打ち切られています]

関連スキル