url-to-markdown

URL から Markdown へ

概要

このスキルを使うと、公開 URL を取得して Markdown に変換し、後でエージェントが利用できるよう、タイムスタンプ付きの Markdown ファイルとして保存できます。

変換の優先順位は固定されています。

1. https://r.jina.ai/<url>（優先）
2. https://markdown.new/（r.jina.ai が利用できない場合のみフォールバック）

このスキルは実行を重視しています。ワークフローを手動で再現するのではなく、同梱のスクリプトを実行してください。

使用する場合

次のような依頼があった場合に、このスキルを使用します。

• URL またはウェブページを Markdown に変換する
• 記事、ドキュメントページ、ブログ記事を .md として保存する
• 後で要約または情報抽出するために公開ウェブページを取り込む
• ページの内容を機械で扱いやすいテキスト形式で保持する
• ドキュメントページをローカルの Markdown ファイルに取り込む

次の場合は、このスキルを使用しないでください。

• ブラウザーへのログインが必要な非公開ページ
• ユーザーにアクセス権限がないサイト
• 単一ページの取得ではなく、サイト全体のクロールが必要なタスク

入力

スクリプトを実行する前に、次の入力を決めてください。

• url：必須（単一 URL モード）。公開 URL である必要があります
• urls：任意。複数 URL の一括変換用（位置引数の url とは併用できません）
• concurrency：任意。並行して変換する数（デフォルトは 3）。一括モードで使用します
• output_dir：任意。一括変換の出力ディレクトリ。スラッグに基づいたファイル名が作成されます
• method：任意。auto、ai、browser のいずれか。デフォルトは auto。markdown.new へのフォールバック時に使用します
• retain_images：任意。デフォルトは false。markdown.new へのフォールバック時に使用します
• transport：任意。auto、get、post のいずれか。デフォルトは auto。markdown.new へのフォールバック時に使用します
• timeout：任意。デフォルトは 30
• force_markdown_new：任意。デフォルトは false。true の場合、r.jina.ai をスキップして markdown.new を直接呼び出します
• output：デフォルトは ./output/（現在のディレクトリ + output/）。ユーザーがプロンプトで出力パスを明示的に指定した場合は、そのパスを使用します

ユーザーがこれらのオプションを指定しない場合は、デフォルトを維持してください。

出力パスのルール：

• url_to_md.py を実行する際は、必ず --output を指定してください。
• ユーザーのプロンプトで出力パスが明示的に指定されている場合は、そのパスをそのまま使用してください。
• それ以外の場合は、--output "output/" を使用してください（現在の作業ディレクトリからの相対パス）。

スクリプトの実行

スキルのディレクトリから、次を実行します。

python scripts/url_to_md.py "<url>" --output "output/"

よく使うバリエーション：

python scripts/url_to_md.py "<url>" --output "output/"
python scripts/url_to_md.py "<url>" --method browser --retain-images --output "output/"
python scripts/url_to_md.py "<url>" --transport post --timeout 45 --output "output/"
python scripts/url_to_md.py "<url>" --force-markdown-new --output "output/"
python scripts/url_to_md.py "<url>" --output "<user_explicit_path>"

一括変換：

# Batch convert multiple URLs with parallel processing (default concurrency=3)
python scripts/url_to_md.py --urls "https://example.com" "https://example.org" "https://example.net" --output-dir "output/"

# Batch with custom concurrency
python scripts/url_to_md.py --urls "https://a.com" "https://b.com" "https://c.com" "https://d.com" "https://e.com" --concurrency 5 --output-dir "output/"

# Single URL in batch mode
python scripts/url_to_md.py --urls "https://example.com" --output-dir "output/"

動作に関する注意事項：

• スクリプトは必ず最初に r.jina.ai を試します。
• --force-markdown-new が設定されている場合、スクリプトは r.jina.ai をスキップし、markdown.new を直接使用します。
• r.jina.ai が利用できない場合（タイムアウト、ネットワーク障害、5xx、レート制限など）のみ、markdown.new にフォールバックします。
• スキルレベルのデフォルトの出力ディレクトリは ./output/ です。実行時には必ず --output を含めてください。
• --output がファイル名の場合、拡張子の前にタイムスタンプが追加されます。
• --output がディレクトリの場合、スラッグに基づいたファイル名とタイムスタンプが付いたファイルが作成されます。

必須の出力動作

次の両方を出力することを優先してください。

1. 保存した Markdown ファイル
2. 簡潔な会話形式の要約

要約には、次の内容を含めてください。

• ソース URL
• 変換に成功したかどうか
• 使用したプロバイダー：r.jina.ai または markdown.new
• ファイルを書き込んだ場合は、保存先のファイルパス
• デフォルト以外の主要なオプション：method、retain_images、transport、timeout

要約テンプレート

次の構成を使用してください。

Source URL: <url>
Status: success
Provider: <r.jina.ai|markdown.new>
Saved Markdown: <path>
Options: method=<value>, retain_images=<value>, transport=<value>, timeout=<value>

デフォルトを使用した場合は、Options を簡潔にしてください。

エラー処理

スクリプトが失敗した場合：

• URL から Markdown への変換に失敗したことを伝えてください
• 主なエラーを簡潔に含めてください
• ページの内容を捏造しないでください
• 明らかな場合は、考えられる原因（ネットワークの問題、タイムアウト、レート制限、サポート対象外のページアクセス）に言及してください

両方のプロバイダーが失敗した場合は、先に失敗したプロバイダーと最後に失敗したプロバイダーを報告してください。 サービスがレート制限を返した場合は、その旨を直接報告し、再試行が成功したかのように装わないでください。

注意事項

• エージェントがローカルファイルをより確実に再利用できるため、標準出力の生データより、保存した Markdown を優先してください。
• 同梱のスクリプトは Python の標準ライブラリのみを使用します。
• スクリプトはインポートしての使用と CLI での実行の両方に対応していますが、このスキルでは通常 CLI を使用してください。