xls-skill: ExcelからMarkdownへの変換(画像をセル内に保持)

Excelワークブック(.xlsx/.xlsm/.xls)をAIが読み取り可能なMarkdownに変換します。セル内に埋め込まれた画像(WPS Officeの=DISPIMGやMicrosoft 365の「セル内に配置」など)やフローティング画像、テキストボックス、数式、結合/非表示の構造、OCRテキストをすべて元の位置に配置。写真、ラベル、ロゴ、スクリーンショット、図面、署名がセルやグリッド上にあるスプレッドシートの読み取り、変換、監査、質問応答に最適です。

xls-skill: ExcelからMarkdownへの変換(画像をセル内に保持) とは?

このスキルは、Excelワークブック(.xlsx/.xlsm/.xls)をMarkdown形式に変換し、画像を元のセル位置に保持するためのツールです。通常のExcelリーダー(openpyxl、pandasなど)はセルの値しか読み取れず、WPS Officeの=DISPIMGやMicrosoft 365の「セル内に配置」機能で埋め込まれた画像を見逃しますが、本スキールはそれらを抽出してMarkdownテーブル内の該当セルに埋め込みます。フローティング画像やテキストボックス、数式、結合セル、非表示行/列も処理し、OCR機能で画像内のテキストも抽出可能。Claude CodeやCursor、CodexなどのAIエージェントで使用でき、変換後は各ワークブックに対してMarkdownファイル、画像ファイル、各種マニフェスト(画像、数式、図形)、変換レポートが出力されます。注意点として、.emf/.wmf画像は変換が必要、チャートは描画されない、ヘッダー/フッター内の画像は抽出されないなどの制限があり、不完全な変換は手動レビューが必要であることを明示します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hougw/xls-skill/tree/HEAD

Installed? Explore more 生産性&コラボレーション skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

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

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

プレビュー

スキル README より

Parts!B2

ドキュメント

xls-skill: Excel -> Markdown、画像をセル内に保持

なぜこのスキールが必要か

ほとんどのExcelリーダー(openpyxl、pandas、CSVエクスポート)はセルの値しか認識しません。以下の2種類の画像が失われます。

  1. セル内画像:画像がセルのコンテンツそのもの。
    • WPS Office「セル内に埋め込む」:セルには =DISPIMG("ID_...",1) のみ表示。画像は xl/cellimages.xml に格納。
    • Microsoft 365「セル内に配置」 / IMAGE:セルには #VALUE! が表示。画像は xl/metadata.xml と xl/richData/ から取得。
  2. フローティング画像やテキストボックス:グリッド上に描画されたもの(プロセス写真、ラベル、フォーム番号など)。

このスキールはこれらすべてを抽出し、各画像をファイルとして保存し、Markdownテーブルの該当セルに書き戻すため、読者はテーブルと画像を一緒に見ることができます。

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | ブラケット | ![Parts!B2](images/01_Parts_B2_cell1.png) | ブラケット \| セル内画像 | 4 |

実行方法

python <skill-dir>/scripts/xlsx_to_md.py <ファイルまたはフォルダ> [...] -o <出力ディレクトリ> [--ocr auto|off] [--ocr-lang eng+chi_sim]
  • .xlsx、.xlsm、.xls、またはフォルダ(再帰的)を受け入れます。ワークブックごとに画像数を1行で出力します。
  • Python 3.9以上と openpyxl が必要。オプション:Pillow(画像サイズ)、Tesseract OCR(画像内テキスト)、Microsoft ExcelまたはLibreOffice(.xls を開くため)。
  • セルフテスト:python <skill-dir>/tests/run_tests.py でWPSおよびMicrosoft 365の疑似ワークブックを生成し、すべての画像が正しいセルに配置されているか確認します。

ワークブックごとに得られるもの(<出力ディレクトリ>/<名前>/)

ファイル内容
<名前>.mdワークブックインデックス、各シートを完全なMarkdownテーブル(切り詰めなし)で画像をセル内にインライン表示;各テーブルの上にシート情報(非表示状態、結合範囲、非表示行/列、コメント、テキストボックス、チャート数)
<名前>.images.md画像ごとに1エントリ:画像、シート!セル、種類、サイズ、近隣セルのテキスト、OCRテキスト、説明スロット
images/すべての画像をファイルとして保存。ファイル名は `<シート番号><シート名><セル>_<セル
sheets_csv/シートの値;画像セルは [image: images/...] と表示
image_manifest.csvシート、セル、種類(in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / floating)、ファイル、パッケージパート、代替テキスト、サイズ、OCR、近隣テキスト
formula_manifest.csvセルごとの数式テキストと計算値
shapes_manifest.csvフローティングテキストボックス/図形からのテキスト、アンカーセル付き
conversion_report.jsonカウント、警告、review_required

エージェントのワークフロー

  1. 変換:スクリプトをワークブックに対して実行します。
  2. 最初にレポートを読む:conversion_report.json を開き、すべての警告に対処:
    • image not found in package(パッケージ内に画像が見つからない) -> セルは [image missing: ID] とマークされます。その旨を伝え、画像を推測しないでください。
    • .emf/.wmf saved as-is(.emf/.wmfがそのまま保存) -> 参照する前にPNGに変換(WindowsではPillow、それ以外ではLibreOfficeなど)。
    • charts > 0 -> チャートはカウントされ、描画されません。チャートが重要な場合はシートを開くかエクスポートしてください。
    • OCRがスキップされた、または言語が見つからない -> 自分で画像を確認してください。
  3. 画像を確認:<名前>.images.md にリストされたすべてのファイルを開き、各 description(説明)プレースホルダーを画像が示す内容に置き換えます:オブジェクト、読み取り可能なテキスト(ラベル、型番、マーク)、シンボル、そして近隣セルとの関連。OCRはヒントであり、答えではありません。小さなラベルテキストは多くの場合、切り抜きや拡大が必要です。
  4. テーブルと画像を合わせて回答:Markdownテーブルから正確なセル値、数式、構造を取得。画像から「どのように見えるか / 部品に何が書かれているか」を取得。両方に シート!セル を引用します。
  5. ギャップを正直に報告:ステップ2で未解決の問題が残っている場合、そのワークブックは手動レビューが必要とマークします。

ルール

  • CSVや値のみのテーブルは、ワークブックに画像、テキストボックス、色、非表示コンテンツがある場合、完全な証拠にはなりません。シート情報とマニフェストを確認してください。
  • 各画像をそのセルおよび隣接セルとペアにし、画像の順序だけで判断しないでください。
  • 重要なテキストはセルの外側にある場合があります:テキストボックス(フォーム番号、改訂マーク)、コメント、ヘッダー/フッター。テキストボックスとコメントは抽出されます。ヘッダー/フッターは抽出されません。文書番号がない場合はExcelで確認してください。
  • 色はデータ(合格/不合格、リスクレベル、ステータス)である可能性があります。このスクリプトは塗りつぶしや条件付き書式をデコードしません。色に意味がある場合は、openpyxlまたはページエクスポートで調査し、マッピングを明示してください。
  • 結合範囲は左上のセルにのみ値が保持されます。空白セルを解釈する前に merged:(結合)行を読んでください。
  • 非表示のシート、行、列は変換され、リストされ、削除されません。回答が非表示コンテンツからのものである場合はその旨を伝えてください。
  • 端末内の文字化けしたパスを信用しないでください。ファイルが存在することを報告する前に、実際のパスを確認してください。

制限事項

  • フローティング画像は左上のアンカーセルに関連付けられます。複数のセルにまたがる画像は、マニフェストに to_cell(宛先セル)とともにリストされます。
  • グループ化された図形は読み取られますが、別々の図形として描画された矢印や吹き出しは、ページレンダリングでのみ写真との関係が維持されます。レイアウトが重要な場合(「どの矢印がどこを指しているか」)は、ExcelまたはLibreOfficeでシートをPDF/PNGにエクスポートし、Markdownと一緒に確認してください。
  • ヘッダー/フッター内の画像(VML)およびコメント内の画像は抽出されません。
  • .xls は最初に変換するためにMicrosoft Excel(Windows、pywin32)またはLibreOfficeが必要です。これらがない場合はセルの値のみが読み取られ、レポートにその旨が記載されます。

関連スキル