markitdown

MarkItDown

Microsoft の markitdown CLI を使って、ドキュメント、画像、音声ファイル、または YouTube URL を Markdown に変換します。このスキルは入力を検証し、適切なフラグを組み合わせ、必要に応じて ~/.agents/output/<project>/markitdown/<slug>/ に結果を保存し、完全に展開された絶対パス（チルダや省略表記なし）を含む一行の概要を報告します。

決定論的な処理（インストール確認、検証、スラッグの導出、保存パス、コマンドの組み立て）は scripts/markitdown.sh で行われます。このスキルは $ARGUMENTS を解析してスクリプトに渡し、スクリプトの RESULT: 行を人が読めるレポートに変換します。

インストール

pip install 'markitdown[all]'

必要なものだけを選んで、より小規模にインストールできます。

グループ	追加される機能
[pdf]	PDF の解析
[docx]	Word ドキュメント
[pptx]	PowerPoint
[xlsx] [xls]	Excel
[outlook]	Outlook .msg
[audio-transcription]	MP3/WAV の文字起こし。現在のコンバーターは音声を Google の音声認識に送信します
[youtube-transcription]	YouTube の文字起こし
[az-doc-intel]	Azure Document Intelligence バックエンド

Azure Document Intelligence を使用する場合は、-d を指定して実行する前に、MARKITDOWN_DOCINTEL_ENDPOINT=https://<resource>.cognitiveservices.azure.com/ もエクスポートしてください。

パラメーター

フラグ	デフォルト	効果
-s	オフ	Markdown を ~/.agents/output/<project>/markitdown/<slug>/<stem>.md に保存します
-S	オフ	保存しない設定を強制します（周囲の保存モードを上書きします）
-d	オフ	Azure Document Intelligence を使用します（MARKITDOWN_DOCINTEL_ENDPOINT が必要です）
-p	オフ	インストール済みのサードパーティ製 markitdown プラグインを有効にします
-k	オフ	データ URI（base64 画像）を出力にインラインで保持します
-l	—	インストール済みプラグインを一覧表示して終了します

出力は ~/.agents/output/{project}/markitdown/{slug}/ に保存されます。{project} は git のトップレベルディレクトリ（ない場合は cwd）のベース名を kebab-case にしたもので、{slug} は入力のベース名を kebab-case にしたもの（単語数は最大 5 つ）です。パイプラインでの利用に適しています。一般的な後続処理では、/forge -s -f <path> で抽出したコンテンツをワークストリームに分解し、/apex -f <path> でそれを基に実装します。-f を受け付けるスキルであれば、どれでも利用できます。

ワークフロー

1. 引数または曖昧さのないセッションコンテキストから対象を特定します。対象が未指定または曖昧な場合に限り、質問してください。音声、OCR、Azure、プラグインによる変換の前に、インストール済みのバックエンドと必要なデータ転送の承認を確認してください。オプションの依存関係グループがあっても、ローカル処理が行われるとは限りません。

2. ヘルパーを実行します。

   $SKILL_DIR = このスキルのフォルダーです。Claude Code では ${CLAUDE_SKILL_DIR}、それ以外ではこの SKILL.md を含むディレクトリです。

   bash "$SKILL_DIR"/scripts/markitdown.sh -s '/absolute/path/report.pdf'
   

   引数はデータとして解析し、各フラグや値をシェルクォートして個別に渡してください。生の $ARGUMENTS をシェルコードに直接埋め込んだり、eval を使用したりしてはいけません。

3. スクリプトは RESULT: key=value の行を出力します。キーは bytes、slug、saved で、保存時には path も含まれます（順序は保証されないため、キーで解析してください）。続いて、変換後の Markdown（保存しないモードでは --- 区切りの後）か、何も出力されない場合（保存モード。ファイルはディスク上にあります）のいずれかになります。

4. RESULT: 行を解析し、以下のレポートを作成します。

5. スクリプトが ERR: markitdown not installed で終了した場合（終了コード 127）は、## インストール のインストールコマンドを表示して停止します。ユーザーに代わって自動インストールしてはいけません。

6. スクリプトがその他の ERR:（ファイルが見つからない、エンドポイントが未設定、不明なフラグ）で終了した場合は、メッセージを一字一句そのまま伝えて停止します。

出力

markitdown: <input> → <bytes> bytes of Markdown
saved: <path>      # only when -s

保存時は、実際のファイルパスを報告してください。出力が長い場合、依頼に沿うのであれば保存モードを選択するか、承認済みの一時ファイルに標準出力を一度だけ取得し、範囲を限定したプレビューと保持した結果を提示してください。表示を短くするためだけに、コストのかかる変換を繰り返してはいけません。

使用例

/markitdown ~/Downloads/report.pdf            # convert, print to terminal
/markitdown -s ~/Downloads/report.pdf         # convert + save under ~/.agents/output/<project>/markitdown/report/
/markitdown -s -p deck.pptx                   # use third-party plugins (e.g. markitdown-ocr)
/markitdown -d invoice.pdf                    # Azure Document Intelligence
/markitdown -k brand.html                     # keep base64 images inline
/markitdown https://youtu.be/dQw4w9WgXcQ      # YouTube transcript
/markitdown -l                                # list installed plugins, then exit

注意事項

• YouTube URL は https?:// プレフィックスで検出され、そのまま markitdown に渡されます。スラッグは URL の最後のパスセグメントから生成されるため、保存先のパスは ~/.agents/output/<project>/markitdown/dqw4w9wgxcq/dQw4w9WgXcQ.md のようになります。
• 検証済みの 0.1.7 コンバーターでの 音声文字起こし には recognize_google が呼び出されます。ローカルの Whisper ではありません。処理の前に、インストール済みの実装とMicrosoft のソースを確認してください。ローカル処理のみを求めるリクエストには、実際にローカルで動作するよう設定されたツールが必要です。ローカル処理を約束している場合、音声を外部に送信しないでください。
• 画像の OCR には、対応するバックエンドが設定されている必要があります。Microsoft の OCR プラグインの手順では、llm_client とモデルが必要です。プラグインをインストールして -p を渡すだけでは不十分です。OCR を利用できない場合は、その旨を明示して報告してください。また、設定とデータの送信方法が許可されている場合に限り、文書化された統合を使用してください。
• 保存出力の競合がある場合、変換前に失敗します。別の保存先や入力 ID を使用するか、既存の出力を置き換える許可を得てください。スラッグ名を使うだけではファイルは保持されません。

ラッパーを使う理由

markitdown はすでに優れた CLI です。このスキルは、（a）リポジトリの -s/-S/-f 規約に従って、ほかのスキルが出力を連鎖して利用できるようにするため、（b）ユーザーに -x、-m、-d、-e を覚えてもらうことなく、「この PDF を抽出して」という依頼を適切な呼び出しに変換するため、（c）ターミナルで複数 MB の Markdown が誤って表示されないよう、統一された 1 行のレポートを出力するために存在します。