markitdownlisted

# markitdown — 文書を Markdown にして読む Read ツールはテキスト・PDF・画像しか開けない。**`.docx` `.xlsx` `.pptx` `.msg` `.epub` は開いても中身が読めない。** このスキルはそれらを Markdown に変換して読めるようにする。 変換エンジンは Microsoft の [markitdown](https://github.com/microsoft/markitdown)。 **環境に入っていなくても、スクリプトが自分で用意する。** 事前準備は要らない。 --- ## 使い方 このスキルのディレクトリを `$SKILL` とする。 ```bash python3 "$SKILL/scripts/md_convert.py" <ファイル・フォルダー・グロブ> [オプション] ``` 結果は **JSON のマニフェスト**で返る。本文はファイル（`.md`）に書き出される。 > **Windows では `python` ではなく `py -3` か `python3` を使うこと。** > PATH 上の `python` が Microsoft Store のスタブ（実行せず終了するダミー）である > ことが多く、その場合は何も起きずに終了コード 0 で返る。 > 出力が空で終了コードが 0 だったら、まずこれを疑う。 `markitdown` が入っていなければ、スクリプトが自動で仮想環境を作って導入する （初回のみ2〜5分、約250MB）。2回目以降は一瞬で立ち上がる。 ### 典型例 ```bash # 1ファイル。中身をすぐ見たいので本文ごと受け取る python3 "$SKILL/scripts/md_convert.py" 見積書.pdf --stdout # フォルダーごと。本文は out/ に書き、手元には概要だけ受け取る python3 "$SKILL/scripts/md_convert.py" 資料/ -o out/ # どれを読むか判断したいので、各ファイルの冒頭だけ見る python3 "$SKILL/scripts/md_convert.py" 資料/ -o out/ --head 300 # 拡張子で絞る python3 "$SKILL/scripts/md_convert.py" "契約書/*.docx" -o out/ ``` --- ## いちばん大事な運用ルール — 文脈を食い潰さない **300ページの PDF は 800KB の Markdown になる。そのまま読み込むと文脈が埋まって 本来の作業ができなくなる。** だから既定では本文を返さず、`.md` に書き出して「どこに何文字書いたか」だけを返す。 | 状況 | 使うもの | |---|---| | 1ファイルで、短いと分かっている | `--stdout` | | 1ファイルだが長いかもしれない | `-o out/` → `chars` を見てから Read | | 複数ファイル | `-o out/` → マニフェストを見て、**必要なものだけ** Read | | どれが当たりか探したい | `-o out/` → `Grep` で `out/` を横断検索 | 複数ファイルに対して `--stdout` は効かない（安全のため無視される）。 `--head` は**判断材料**であって本文ではない。300〜500 文