convert-word-to-md

Word を Markdown に変換する

このスキルを使用する場面

理解または処理が必要な .docx ファイルがある場合は、いつでもこのスキルを起動します。たとえば、ユーザーが Word 文書を添付して内容について質問したり、要約を求めたり、特定のデータを抽出したり、フォルダー内の複数の Word 文書をまとめて処理するよう依頼したりする場合です。Word のネイティブな .docx 形式は、ZIP 圧縮された XML の集合体であり、プレーンテキストとして確実に読み取れるとは限りません。そのため、ファイルを直接開いたり解析したりせず、必ずこのスキルに含まれるスクリプトを使用して、まず Markdown に変換してください。

このスキルが対応しているのは .docx のみです。従来形式の .doc ファイルの変換を依頼された場合は、対応していないことをユーザーに伝え、まず .docx として再保存するよう依頼してください（Word：［ファイル］>［名前を付けて保存］>［Word 文書（.docx）］）。

複数のファイル形式が混在する場合： ユーザーが、複数の対応ファイル形式（.pdf、.docx、.xlsx）を含むフォルダーまたは文書セットを指定した場合、このスキルが処理するのは .docx ファイルのみです。エージェントは、該当する次のスキルも並行して必ず呼び出してください。

• .pdf ファイルには convert-pdf-to-md
• .xlsx ファイルには convert-excel-to-md

対応するファイル形式を黙ってスキップして、フォルダーを処理してはいけません。複数のファイル形式が混在している場合は、3 つのスキルをすべて同時に呼び出してください。

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

ある環境で最初に変換する前に、Python、pip、および markitdown パッケージがインストールされていることを確認するため、references/setup.md の手順を順番に実施してください。環境が準備済みかどうかを推測するのではなく、あらかじめ確認してください。markitdown がインストールされていない場合は、スクリプト自体がそのファイルを明示して失敗するため、セットアップがすでに完了していると十分に確信できる場合は、まず変換を試しても問題ありません。

使い方

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

出力の構造： MarkItDown は画像を、実際の画像データではない、途中で切り詰められた data:image/png;base64... URI のプレースホルダーとして埋め込みます。そのため、スクリプトは .docx から画像を直接抽出し、単独の .md ファイルではなく、各文書専用の自己完結型フォルダーに出力します。

<name>/
    img/
        img001.<ext>
        img002.<ext>
        ...
    <name>.md          (image references are relative: img/imgNNN.ext)

文書に埋め込み画像がない場合、img/ フォルダーは作成されません。

単一ファイル：

# Windows
python scripts\convert_word_to_md.py "C:\path\to\document.docx"

# macOS / Linux
python scripts/convert_word_to_md.py "/path/to/document.docx"

これにより、元のファイルと同じ場所に document\ フォルダーが作成されます（document.md と、画像がある場合は document\img\ が含まれます）。出力先フォルダーを明示的に指定するには：

python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"

Word 文書のフォルダー（バッチモード）：

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

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

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

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

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

出力先の決定方法

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

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

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

トラブルシューティング

症状	考えられる原因	対処方法
ModuleNotFoundError: No module named 'markitdown' / 終了コード 2	MarkItDown がインストールされていません	references/setup.md に従ってください
ERROR: Unsupported file type '.doc' / 終了コード 3	.docx ではなく旧形式の .doc です	ユーザーに .docx 形式で再保存するよう依頼してください
ERROR: Input path not found / 終了コード 3	パスが間違っているか、ファイルが移動されています	正しいパスをユーザーに確認してください
バッチ出力に FAILED <file> -> ... と表示される	そのファイルが破損している、パスワードで保護されている、またはその他の理由で読み取れません	失敗したファイルを報告してください。バッチ内のほかのファイルは引き続き処理されます
NOTE: skipped N non-.docx file(s)	フォルダーに Word 以外のファイルが含まれています	想定どおりです。これらのファイルは意図的に無視されます
WARNING: found N image placeholder(s) ... but extracted M image file(s)	MarkItDown のプレースホルダー数と word/media/ 内で見つかった画像数が一致しません（通常とは異なる形式、または不正な docx）	誤った画像を割り当てる危険を避けるため、プレースホルダーは置き換えられません。画像が必要な場合は、ソースファイル内のメディアを手動で確認してください