convert-excel-to-md

Excel を Markdown に変換する

このスキルを使用するタイミング

理解または処理が必要な .xlsx ファイルがある場合は、いつでもこのスキルを起動してください。たとえば、ユーザーがスプレッドシートを添付して質問した場合、データの要約を求めた場合、特定の行や値の抽出を求めた場合、またはフォルダー内の複数のブックをまとめて処理したい場合などです。Excel のネイティブな .xlsx 形式は、圧縮された XML の集合体であり、プレーンテキストとして確実に読み取れるものではありません。そのため、ファイルを直接開いたり解析したりするのではなく、必ずこのスキルのスクリプトを使って最初に Markdown に変換してください。

このスキルが対応するのは .xlsx のみです。従来の .xls ファイルの変換を求められた場合は、対応していないことを伝え、まず .xlsx として再保存するようユーザーに依頼してください（Excel：「ファイル」>「名前を付けて保存」>「Excel ブック（.xlsx）」）。

複数のファイル形式が混在している場合： ユーザーが、複数の対応ファイル形式（.pdf、.docx、.xlsx）を含むフォルダーまたはドキュメント一式を指定した場合、このスキルでは .xlsx ファイルのみを処理します。エージェントは、以下の関連スキルも並行して必ず起動してください。

• .pdf ファイルには convert-pdf-to-md
• .docx ファイルには convert-word-to-md

対応ファイル形式があるのに、フォルダーを処理する際にそれを黙ってスキップしてはいけません。複数の形式が混在している場合は、3 つすべてのスキルを同時に起動する必要があります。

セットアップ（環境ごとに 1 回）

特定の環境で最初に変換する前に、references/setup.md の手順に従って、Python、pip、および markitdown パッケージがインストールされていることを確認してください。環境の準備状況を推測するのではなく、あらかじめ実施してください。markitdown が見つからない場合はスクリプトからもこのファイルを参照するよう明確に案内されるため、セットアップ済みだと十分に確信できる場合は、まず変換を試しても安全です。

使い方

変換スクリプトは scripts/convert_excel_to_md.py にあります。

出力構造： MarkItDown の XLSX コンバーターは、各シートを独立した ## <SheetName> の Markdown テーブルとして出力します。埋め込み画像にはまったく対応していません。このスクリプトは、実際に埋め込まれた画像（グラフではなくラスター画像）を別途抽出して、該当するシートに対応付け、ドキュメントごとの自己完結型フォルダーに書き込みます。

<name>/
    img/
        sheet001_<sheetname>_img001.<ext>
        sheet002_<sheetname>_img001.<ext>
        ...
    <name>.md          (each sheet's images appear right after its table,
                         under a "#### Images in this sheet" heading)

画像の配置はシート単位であり、セルの正確な位置を示すものではありません。MarkItDown の安定した出力で位置の目印となる ## <SheetName> 見出しを利用できる範囲で、最も細かい粒度となります。ブックに埋め込み画像がない場合、img/ フォルダーも画像セクションも作成されません。Excel ネイティブのグラフは画像として抽出されません（実際に埋め込まれた画像のみが対象です。グラフの抽出には Excel／LibreOffice でのレンダリングが必要ですが、この軽量なスキルでは行いません）。

単一ファイル：

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"

ソースファイルと同じ場所に workbook\ フォルダーが作成されます（workbook.md と、存在する場合は workbook\img\ が含まれます）。出力先フォルダーを明示的に指定するには、次のようにします。

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"

ブックが入ったフォルダー（バッチモード）：

python scripts\convert_excel_to_md.py "C:\path\to\folder"

サブフォルダーも含めるには、--recursive を追加します。

python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive

見つかった各 .xlsx ファイルの隣に、デフォルトでそれぞれ独自の <name>\ 出力フォルダーが作成されます。-o "C:\path\to\output_parent" を指定すると、生成されたすべての <name>\ フォルダーを別の親ディレクトリにまとめられます（--recursive と併用した場合はサブフォルダーの構造が維持されます）。

変換後は、生成された .md ファイルを読み込み、ユーザーが求めた分析を実施してください。スクリプトの役割は、正確な Markdown（および画像）を生成することだけであり、内容を解釈することではありません。

出力先の決定

デフォルト — 常にソースファイルと同じ場所に出力します。 <name>/ フォルダーは、ソースの .xlsx と同じディレクトリに作成されます。これはすべての場合に適用される必須のデフォルトです。ユーザーが別の場所を明示的に指定しない限り、上書きしないでください。

**-o を使用するのは、**ユーザーが出力先を明示的に指定した場合のみです（例：「出力を C:\output に保存して」「結果を D:\work に入れて」）。エージェントの現在の作業ディレクトリ、セッション状態フォルダー、または暗黙的に示された場所に基づいて -o を指定しないでください。

ソースファイルのパスを完全に解決できない場合 — たとえば、ユーザーがディレクトリを指定せずにファイル名だけを提示した場合や、パスが曖昧な場合 — 変換を実行する前に ask_user を使用して絶対パス全体を確認してください。ディレクトリを推測したり、決めつけたりしないでください。

トラブルシューティング

症状	考えられる原因	解決方法
ModuleNotFoundError: No module named 'markitdown' / exit code 2	MarkItDown がインストールされていません	references/setup.md に従ってください
ERROR: Unsupported file type '.xls' / exit code 3	旧形式の .xls であり、.xlsx ではありません	ユーザーに .xlsx として再保存するよう依頼してください
ERROR: Input path not found / exit code 3	パスが間違っているか、ファイルが移動されています	ユーザーに正しいパスを確認してください
バッチ出力に FAILED <file> -> ... と表示される	そのファイルが破損している、パスワードで保護されている、またはその他の理由で読み取れません	失敗したファイルを報告してください。バッチ内のその他のファイルは引き続き正常に処理されます
NOTE: skipped N non-.xlsx file(s) と表示される	フォルダーに Excel 以外のファイルが含まれています	想定どおりです。これらのファイルは意図的に無視されます
シートのグラフが画像として表示されない	グラフは埋め込み画像ではなくグラフオブジェクトです。このスキルで抽出できるのは、実際に埋め込まれたラスター画像のみです	想定どおりです。ユーザーが特にグラフ画像を必要としている場合は、この制限について説明してください