web-to-markdown

web-to-markdown スキルの概要

web-to-markdown は、ローカルにインストールした web2md CLI を使って、公開中のWebページを読みやすい Markdown に変換することに特化した Format Conversion スキルです。価値の中心は「ページを要約すること」ではなく、「実際のブラウザでページを描画し、記事やドキュメントの本文を抽出し、その結果を持ち運びやすい Markdown に変換すること」にあります。JavaScript で描画されるページ、ドキュメントサイト、ブログ記事、インタラクティブな操作が必要な制限付きフロー、あるいは単純な HTTP 取得では足りないアーカイブ用途に特に向いています。

web-to-markdown が最も向いている人

この web-to-markdown スキルは、次のようなニーズがあるユーザーに適しています。

• 1つまたは複数の URL を読みやすい Markdown に変換したい
• クライアントサイド JavaScript に依存するページを扱いたい
• あとで分析や再利用をするために、内容をファイルとして保存したい
• ページ全体の要素を無差別に取るのではなく、記事本文のような主要コンテンツを抽出したい

本当の目的が「ブラウザで見えているページの主要コンテンツを取り出したい」なら、汎用的なプロンプトよりこのスキルのほうが適しています。

web-to-markdown が他と違うポイント

大きな違いは、次の処理パイプラインにあります。

• ローカルの Chromium 系ブラウザを Puppeteer で操作
• 本文抽出に Readability を使用
• Markdown 変換に Turndown を使用

この組み合わせは、生の HTML ではなく「描画後のコンテンツ」を前提に設計されています。実運用では、通常の fetch ベースのツールだと失敗したり不完全な内容しか返せないページでも、web-to-markdown なら通るケースがあります。

厳格なトリガー条件は重要

このスキルには少し珍しいですが重要な制約があります。use the skill web-to-markdown のように、ユーザーが名前を明示して要求した場合にしか使ってはいけません。この明示的なトリガーがない限り、スキルは適用されません。ディレクトリ利用者にとって導入自体は簡単ですが、呼び出し方のルールはきちんと守る必要があります。

実際のジョブ・トゥ・ビー・ダン

多くのユーザーが欲しいのは「ブラウザ自動化スキル」そのものではありません。求めているのは、たとえば次のような結果です。

• 「この記事を保存しやすい Markdown にしたい」
• 「クライアントサイドで描画される docs ページを Markdown 化したい」
• 「複数の URL をまとめて .md ファイルにしたい」
• 「ログインや認証をブラウザで通過してから内容を保存したい」

web-to-markdown は、まさにこうした用途に最適化されています。

このスキルを選ばないほうがいい場面

次のような場合は、web-to-markdown は見送ったほうが適切です。

• Markdown 出力ではなく、手早い要約だけが欲しい
• 単純な HTTP fetch ですでに十分きれいに内容が取れる
• フルクローラーやサイト全体のスクレイピングが必要
• Playwright ベースの自動化を使いたい。これは明確に web2md 用のスキルであり、別のブラウザスタック向けではありません

web-to-markdown スキルの使い方

初回利用前に確認したいインストール前提

web-to-markdown は、次の2つの依存関係がそろって初めて使えるものとして考えるとわかりやすいです。

1. エージェント環境にスキル本体が入っていること
2. ローカルで動作する web2md CLI と、利用可能な Chromium 系ブラウザがあること

実用的なスキル導入コマンドは次のとおりです。

npx skills add softaworks/agent-toolkit --skill web-to-markdown

リポジトリはこちらです。
https://github.com/softaworks/agent-toolkit/tree/main/skills/web-to-markdown

ただし、スキルを追加しただけでは不十分です。マシン側で web2md が実行できない、あるいは Chrome / Chromium / Brave / Edge を起動できない場合、実際には使えません。このローカルブラウザ要件が、導入時に最初に確認すべき最大のハードルです。

最初に読むべきファイル

このスキルは小規模なので、読む順番は次の2つで十分です。

1. skills/web-to-markdown/SKILL.md
2. skills/web-to-markdown/README.md

SKILL.md では、トリガールール、必要な入力、処理の流れを把握できます。README.md では、JS 描画ページ、インタラクティブモード、一括変換といった想定ユースケースを確認できます。

web-to-markdown に必要な入力

web-to-markdown を安定して使うには、次の情報を渡すのが基本です。

• url または URL の一覧
• 出力方法
  • --print で標準出力に表示
  • --out ./file.md でファイルに保存
  • --out ./some-dir/ でディレクトリに保存
• 必要に応じたブラウザ制御
  • ブラウザ検出に失敗する場合は --chrome-path <path>
  • ログイン画面、同意画面、人間確認がある場合は --interactive

出力方法を指定しないと、エージェント側で推測するしかありません。これは無駄な摩擦になりやすく、最初から明示しておくのがいちばん簡単です。

厳密な呼び出し条件

この web-to-markdown スキルは、ユーザーが明示的に次のような書き方をした場合にのみトリガーされるべきです。

• use the skill web-to-markdown ...
• use a skill web-to-markdown ...

スキルを試すときは、名前をそのまま書いてください。これは単なるリポジトリ上の作法ではなく、実行ロジックの中核です。

あいまいな依頼を、通りやすいプロンプトに変える

弱い依頼:

• convert this page

強い依頼:

• use the skill web-to-markdown to convert https://example.com/article to Markdown and save it to ./notes/article.md

さらによい例:

• use the skill web-to-markdown to convert these 5 docs URLs to Markdown, save them in ./docs-md/, and use interactive mode if a consent screen appears

よいプロンプトは、スキルに対して次の点を明確に伝えます。

• どのページを処理するのか
• 出力先をどこにするのか
• ブラウザ上での人手操作が必要になりそうか
• 単発処理なのか、一括処理なのか

実際に依頼しやすいコマンドパターン

web-to-markdown の実用的な使い方としては、次のパターンがよくあります。

• 1ページをターミナルに出す: --print
• 1ページをファイルに保存: --out ./page.md
• 複数ページをフォルダに保存: --out ./pages/
• 難しいページを可視ブラウザで処理: --interactive
• ブラウザ実行ファイルを明示: --chrome-path <path>

リポジトリにあるガイダンスに沿うと、こうした具体的なパターンのほうが、「このサイトをスクレイプして」のような設計範囲を超えた依頼よりもずっと成果につながります。

1ページ処理で成功率が高い web-to-markdown の流れ

成功しやすい進め方は次のとおりです。

1. ユーザーが web-to-markdown を明示的に呼び出しているか確認する
2. URL を受け取る
3. 画面出力にするか、保存するかを決める
4. 人手が必要なページだけ --interactive を使う
5. 生成された Markdown に本文欠落やナビゲーション混入がないか確認する
6. 抽出が不完全なら、ブラウザ設定を見直して再実行する

最初からプロンプトを作り込みすぎるより、この流れのほうが早く安定します。

複数 URL を処理するベストな進め方

一括処理では、次の進め方が現実的です。

1. スキルに URL 一覧を渡す
2. 出力先としてディレクトリを指定する
3. フォルダ保存時はページタイトル由来のファイル名になることを想定しておく
4. 大量実行の前に、いくつかの出力を抜き取り確認する

バッチ化の最大の利点は一貫性です。いちばんのリスクは、サイト内のすべてのページテンプレートが同じようにうまく抽出できると思い込むことです。

ローカル環境でよく詰まるポイント

web-to-markdown の導入失敗は、プロンプトの問題でないことがほとんどです。多くはローカル環境側です。

• web2md がインストールされていない、または PATH にない
• 対応ブラウザがローカルに存在しない
• ブラウザ自動検出に失敗し、--chrome-path が必要
• ページ側が可視ブラウザと人手操作を必要とする

まず導入可否を手早く見たいなら、本番ワークフローに入る前に、公開記事ページを1つ、JS 依存の強いページを1つ試すのがおすすめです。

出力品質に期待すべきこと

web-to-markdown が目指すのは、元ページの見た目をピクセル単位で再現することではなく、「主要コンテンツをきれいな Markdown にすること」です。つまり、次のような傾向があります。

• 記事本文やドキュメント本文は比較的うまく取り込める
• ヘッダー、フッター、広告、ページ装飾は通常あまり重視されない
• 特殊なウィジェット、アプリシェル、埋め込みツールはきれいに変換できない場合がある

このトレードオフは、アーカイブや分析用途ではむしろ都合がよいことが多いですが、インストール前に理解しておく価値があります。

web-to-markdown スキル FAQ

web-to-markdown は普通のプロンプトより優れていますか？

はい。必要なのが「描画後のページを Markdown に変換すること」なら、web-to-markdown のほうが適しています。汎用プロンプトでも URL について説明はできますが、ブラウザを開いて JavaScript の実行を待ち、読める本文を抽出し、Markdown にするところまでは自動では行いません。web-to-markdown の価値は、その一連の流れを実運用可能な形にしている点にあります。

web-to-markdown は初心者向きですか？

はい。タスクがシンプルであれば、初心者でも扱いやすいです。たとえば、URL が1つ、出力先ファイルも1つ、ページ構造も素直という条件なら十分現実的です。初心者がつまずきやすいのはスキル設計よりローカルセットアップのほうです。ローカルでブラウザ自動化 CLI を動かせるなら、扱いづらいスキルではありません。

web-to-markdown は JavaScript の重いページにも対応できますか？

それがこのスキルの存在理由のひとつです。Puppeteer 経由で実際のローカルブラウザを使うため、生の fetch ベースの手法よりも、JS 描画ページに向いています。

web-to-markdown でログイン画面や認証画面を越えられますか？

場合によりますが、--interactive を使えば可能なことがあります。リポジトリでも、Chrome を表示して一時停止し、ユーザーが人手で必要な操作を完了できるモードが明示的にサポートされています。保護されたページや半保護状態のページでは、これは実務上かなり便利な強みです。

web-to-markdown スキルを使わないほうがいいのはいつですか？

次のような場合は使わないでください。

• ユーザーが web-to-markdown を明示的に要求していない
• 単純なページ取得で十分に解決できる
• 多数のページ要素を構造化してスクレイピングしたい
• ブラウザを使わない変換経路が必要

このスキルは特化型です。そして、その特化こそが弱点ではなく強みです。

どのブラウザでも使えますか？

ドキュメント上で適合が示されているのは、puppeteer-core 経由で利用する Chrome、Chromium、Brave、Edge などの Chromium 系ブラウザです。自動検出がうまくいかない場合は、手動でパスを渡す前提で考えておくとよいでしょう。

記事ページ専用ですか？

いいえ。記事ページは最も相性がよい例ですが、web-to-markdown は docs ページや、本文抽出が適切なコンテンツ中心のページにも役立ちます。一方で、ダッシュボードや強いインタラクション前提のアプリにはあまり向きません。

web-to-markdown スキルを改善するには

web-to-markdown には出力先を明確に指示する

よい依頼は、単に「この URL を変換して」ではありません。たとえば次のように指定します。

• print it
• save it to ./tmp/page.md
• save all results under ./exports/

これだけで推測の余地が減り、初回実行から自分のワークフローに合いやすくなります。

インタラクティブモードは必要なページだけで使う

--interactive は、同意画面、ログインフロー、認証プロンプトには有効ですが、そのぶん遅く、自動化しにくくなります。通常の公開ページでは避け、ブロックされるページでは手当たり次第に再試行する前に早めに使うのが得策です。

ブラウザ検出は早い段階で確認する

最初の実行でブラウザ起動に失敗したら、プロンプトばかりいじらないでください。直すべきなのは実行コンテキストです。

• Chromium 系ブラウザが存在するか確認する
• 必要なら --chrome-path <path> を渡す

多くのユーザーにとって、これは web-to-markdown 導入時でもっとも重要なチェックポイントです。

大規模展開の前に、代表的なページで試す

何百件もの URL を変換する前に、最低でも次を試してください。

• シンプルな記事ページを1つ
• JS 描画ページを1つ
• 同意やログインの壁があるページを1つ

こうしておくと、理想条件で動くかではなく、自分の実際のサイト構成に web-to-markdown が合うかを見極められます。

ページ固有の難しさはプロンプトに書く

難しいページだと分かっているなら、それを明示してください。

• use the skill web-to-markdown on this docs page; it renders client-side, save to ./docs/intro.md
• use the skill web-to-markdown on this member page with interactive mode because I need to pass a verification screen first

こうした具体情報は、抽象的な言い回しを足すよりも、実行品質にずっと大きく効きます。

最初の Markdown 結果を確認してから調整する

最初の出力ができたら、次を確認します。

• 主要コンテンツは取れているか
• ナビゲーションや定型文が入りすぎていないか
• ページが途中までしか描画されていないか
• ファイル名やフォルダ出力の挙動は期待どおりか

そのうえで、必要な制御を追加して再実行します。web-to-markdown は、長々と推測でプロンプトを練るより、狙いを絞った1回の再試行で改善することが多いです。

典型的な失敗パターンを知っておく

よくある失敗は次のとおりです。

• 明示的なトリガーフレーズがなく、そもそもスキルを実行してはいけない
• ローカルブラウザの起動に問題がある
• ページが可視状態での人手操作を必要とする
• Readability にとって「主要コンテンツ」が判定しにくいページである
• ユーザーがページ変換ではなくサイト全体スクレイピングを期待している

これを早めに見抜けると、web-to-markdown を使い続けるべきか、別ツールに切り替えるべきか判断しやすくなります。

web-to-markdown は適切な出力基準で使う

最もよい結果が出やすいのは、成功条件が次のような場合です。

• きれいで読みやすい Markdown が欲しい
• ページ装飾より主要コンテンツを重視したい
• メモ、アーカイブ、分析、後続の AI 処理に使える持ち運びやすい出力が必要

逆に、「レイアウトの細部まで完全に保持したい」が成功条件なら、このスキルは不向きです。期待値を設計に合わせることが、結果を改善するいちばん速い方法です。