baoyu-url-to-markdown

URL から Markdown へ

baoyu-fetch CLI（Chrome CDP とサイト固有のアダプター）を使って任意の URL を取得し、整った Markdown に変換します。

ユーザー入力ツール

このスキルがユーザーに質問する場合は、次の優先順位に従ってツールを選択してください。

1. 組み込みのユーザー入力ツールを優先してください。例：現在のエージェントランタイムが提供する AskUserQuestion、request_user_input、clarify、ask_user、または同等のツール。
2. フォールバック：そのようなツールがない場合は、番号付きのプレーンテキストメッセージを出力し、各質問に対する選択番号または回答をユーザーに返信してもらいます。
3. まとめて質問：1 回の呼び出しで複数の質問に対応できる場合は、該当する質問をすべてまとめてください。1 回に 1 問のみの場合は、優先順位に従って 1 問ずつ質問してください。

以下の AskUserQuestion の例は参考です。ほかのランタイムでは、ローカルの同等ツールに置き換えてください。

CLI のセットアップ

重要：CLI のソースは {baseDir}/scripts/lib にベンダーとして同梱されています。scripts/package.json では、サードパーティのランタイム依存関係のみをインストールします。

エージェントの実行手順：

1. この SKILL.md ファイルのディレクトリパスを {baseDir} として特定します
2. ${BUN} ランタイムを解決します。bun がインストールされている場合は bun を使用し、そうでない場合は Bun のインストールを提案します
3. {baseDir}/scripts/node_modules が存在しない場合は、${BUN} install --cwd {baseDir}/scripts を実行します
4. ${READER} = {baseDir}/scripts/baoyu-fetch
5. このドキュメント内のすべての ${READER} を、解決した値に置き換えます

設定（EXTEND.md）

優先順位に従って EXTEND.md を確認してください。最初に見つかったファイルを使用します。

優先度	パス	スコープ
1	.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	プロジェクト
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	ユーザーホーム

結果	アクション
見つかった	読み込み、解析し、設定を適用します
見つからない	必ず初回セットアップ（以下を参照）を実行します。デフォルトを黙って作成してはいけません

EXTEND.md で設定できる項目：メディアのデフォルトでのダウンロード、デフォルトの出力ディレクトリ。

初回セットアップ ⛔ ブロッキング

EXTEND.md が見つからない場合は、EXTEND.md を作成する前に、必ず AskUserQuestion を使って設定を確認してください。デフォルト設定を黙って適用して EXTEND.md を作成してはいけません。セットアップが完了するまで生成はブロックされます。次の 3 つの質問を 1 回の呼び出しにまとめてください。

• Q1 — メディア（ヘッダー「Media」）：「ページ内の画像や動画をどのように扱いますか？」
  • 「毎回確認（推奨）」— 保存のたびに確認します
  • 「常にダウンロード」— ローカルの imgs/ と videos/ にダウンロードします
  • 「ダウンロードしない」— リモート URL を保持します
• Q2 — 出力（ヘッダー「Output」）：「デフォルトの出力ディレクトリはどこですか？」
  • 「url-to-markdown（推奨）」— ./url-to-markdown/{domain}/{slug}.md に保存します
  • ユーザーは「その他」を選んで、カスタムパスを入力できます
• Q3 — 保存先（ヘッダー「Save」）：「設定の保存先はどこですか？」
  • 「ユーザー（推奨）」— ~/.baoyu-skills/（すべてのプロジェクト）
  • 「プロジェクト」— .baoyu-skills/（このプロジェクトのみ）

回答を受け取ったら EXTEND.md を書き込み、「設定を [path] に保存しました」と確認してから続行します。

完全なテンプレート：references/config/first-time-setup.md。

対応するキー

キー	デフォルト	値	説明
download_media	ask	ask / 1 / 0	ask = 毎回確認、1 = 常に、0 = なし
default_output_dir	empty	パスまたは空	デフォルトの出力ディレクトリ（空の場合は ./url-to-markdown/）

EXTEND.md から CLI への対応：

EXTEND.md キー	CLI 引数	備考
download_media: 1	--download-media	--output の指定が必要です
default_output_dir: ./posts/	エージェントが --output ./posts/{domain}/{slug}.md を構築	エージェントがパスを生成します。直接指定するフラグではありません

値の優先順位：CLI 引数 → EXTEND.md → スキルのデフォルト。

使い方

# Default: headless capture, markdown to stdout
${READER} <url>

# Save to file
${READER} <url> --output article.md

# Save with media download
${READER} <url> --output article.md --download-media

# Wait for interaction (login/CAPTCHA) — auto-detect and continue
${READER} <url> --wait-for interaction --output article.md

# Wait for interaction — manual control (Enter to continue)
${READER} <url> --wait-for force --output article.md

# JSON output
${READER} <url> --format json --output article.json

# Force specific adapter
${READER} <url> --adapter youtube --output transcript.md

オプション

オプション	説明
<url>	取得する URL
--output <path>	出力ファイルのパス（デフォルト：標準出力）
--format <type>	出力形式：markdown（デフォルト）または json
--json	--format json の省略形
--adapter <name>	アダプターを指定：x、youtube、hn、generic（デフォルト：自動検出）
--headless	ヘッドレス Chrome を強制（ウィンドウを表示しない）
--wait-for <mode>	インタラクションの待機モード：none（デフォルト）、interaction、force
--wait-for-interaction	--wait-for interaction の別名
--wait-for-login	--wait-for interaction の別名
--timeout <ms>	ページ読み込みのタイムアウト（デフォルト：30000）
--interaction-timeout <ms>	ログイン／CAPTCHA の待機タイムアウト（デフォルト：600000 = 10 分）
--interaction-poll-interval <ms>	インタラクション確認のポーリング間隔（デフォルト：1500）
--download-media	画像／動画をローカルの imgs/ と videos/ にダウンロードし、Markdown のリンクを書き換えます。--output が必要です
--media-dir <dir>	ダウンロードしたメディアのベースディレクトリ（デフォルト：--output のディレクトリと同じ）
--cdp-url <url>	既存の Chrome DevTools Protocol エンドポイントを再利用
--browser-path <path>	Chrome／Chromium のカスタムバイナリパス
--chrome-profile-dir <path>	Chrome のユーザーデータディレクトリ（デフォルト：BAOYU_CHROME_PROFILE_DIR 環境変数、または ./baoyu-skills/chrome-profile）
--debug-dir <dir>	デバッグ用データ（document.json、markdown.md、page.html、network.json）を書き込み

エージェントの品質ゲート

重要：デフォルトのヘッドレスキャプチャは暫定的なものとして扱ってください。サイトによってはヘッドレスモードで表示が異なり、CLI がエラーを返さずに品質の低いコンテンツを返すことがあります。

ヘッドレス実行のたびに、保存された Markdown を確認してください。チェックリスト、復旧ワークフロー、キャプチャモードの表については、references/quality-gate.md を参照してください。実行結果に疑わしい点がある場合や、ユーザーからログイン／CAPTCHA の処理について質問された場合は、必ず読んでください。

出力パスの生成

出力ファイルのパスはエージェントが作成する必要があります。baoyu-fetch はパスを自動生成しません。

アルゴリズム：

1. EXTEND.md の default_output_dir、またはデフォルトの ./url-to-markdown/ からベースディレクトリを決定します
2. URL からドメインを抽出します（例：example.com）
3. URL のパスまたはページタイトルからスラッグを生成します（ケバブケース、2～6 語）
4. {base_dir}/{domain}/{slug}/{slug}.md を作成します。メディアファイルを分離できるよう、各 URL に専用のディレクトリを割り当てます
5. 競合がある場合は、タイムスタンプを付加します：{slug}-YYYYMMDD-HHMMSS/{slug}-YYYYMMDD-HHMMSS.md

作成したパスを --output に渡します。メディアファイル（--download-media）は Markdown ファイルの隣にあるサブディレクトリに保存されるため、各 URL のアセットが独立して保管されます。

アダプターとメディア

アダプターのカタログ（X、YouTube、Hacker News、汎用）、アダプターごとの注意事項、メディアのダウンロードフロー（ask／常に／しない）、JSON 出力スキーマについては、references/adapters.md を参照してください。アダプターに関する質問への回答や、メディアに関するプロンプトの処理を行う前に読んでください。

環境変数

変数	説明
BAOYU_CHROME_PROFILE_DIR	Chrome のユーザーデータディレクトリ（--chrome-profile-dir も使用できます）

トラブルシューティング：Chrome が見つからない場合 → --browser-path を使用します。タイムアウトする場合 → --timeout の値を増やします。ログイン／CAPTCHA の場合 → --wait-for interaction を使用します。デバッグする場合 → --debug-dir を指定して、キャプチャした HTML とネットワークログを確認します。

拡張機能のサポート

EXTEND.md を使ってカスタム設定を行えます。パスと対応するキーについては、上記の設定セクションを参照してください。