web-to-markdown

web-to-markdown skill 概覽

web-to-markdown 是一個範圍明確、專注於格式轉換的 skill，透過本機安裝的 web2md CLI，把即時網頁轉成乾淨的 Markdown。它的價值不在於「幫你摘要頁面」，而是在於「用真正的瀏覽器把頁面完整渲染出來、擷取主要文章或文件內容，再轉成可攜式的 Markdown」。因此，對於需要處理 JavaScript 渲染頁面、文件網站、部落格文章、必須互動後才能看到內容的流程，或是單靠簡單 HTTP 抓取不夠用的封存需求，web-to-markdown 特別合適。

哪些人最適合用 web-to-markdown

這個 web-to-markdown skill 最適合以下需求的使用者：

• 將一個或多個 URL 轉成可閱讀的 Markdown
• 處理依賴前端 JavaScript 的頁面
• 把內容存成檔案，方便後續分析或重複使用
• 擷取類似文章主體的內容，而不是把整個頁面的所有元素都抓下來

如果你的真正目標是「把我已經能在瀏覽器裡看到的頁面主內容抓出來」，那這個 skill 會比泛用提示詞更對路。

web-to-markdown 真正不同的地方

它的關鍵差異在於整個處理管線：

• 透過本機 Chromium 系列瀏覽器執行 Puppeteer
• 用 Readability 擷取主要內容
• 用 Turndown 轉成 Markdown

這組合是為了「已渲染完成的內容」而設計，不是直接處理原始 HTML。實務上，這代表 web-to-markdown 能處理不少一般以 fetch 為基礎的工具會失敗、或只能拿到殘缺內容的頁面。

那個嚴格的觸發門檻很重要

這個 skill 有一個不尋常但非常重要的限制：只有在使用者明確點名要求時才能使用，例如寫出 use the skill web-to-markdown 這類字句。若沒有這個明確觸發，skill 就不應該被套用。對技能目錄的使用者來說，這代表採用門檻其實不高，但呼叫方式必須守規則。

使用者真正想完成的工作

大多數人其實不是在找「瀏覽器自動化 skill」，而是想達成以下其中一種結果：

• 「把這篇文章轉成我可以留存的 Markdown。」
• 「把這個文件頁轉成 Markdown，就算它是前端渲染的也要行。」
• 「把一批 URL 批次處理成 .md 檔。」
• 「先用真正的瀏覽器打開頁面，讓我通過登入或驗證，再把內容存下來。」

這才是 web-to-markdown 真正優化的使用情境。

哪些情況不該選這個 skill

遇到以下情況就不建議用 web-to-markdown：

• 你只需要快速摘要，不需要 Markdown 輸出
• 直接用普通 HTTP 抓取就已經能乾淨拿到內容
• 你需要的是完整 crawler 或站點級 scraper
• 你想用 Playwright 為基礎的自動化；這個 skill 明確是用 web2md，不是其他瀏覽器堆疊

如何使用 web-to-markdown skill

第一次使用前，先看清安裝前提

把 web-to-markdown 視為兩個依賴項：

1. 你的 agent 環境裡要先安裝這個 skill
2. 本機要有可用的 web2md CLI，以及一個可啟動的 Chromium 系列瀏覽器

實際可行的 skill 安裝方式如下：

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

Repository 在這裡：
https://github.com/softaworks/agent-toolkit/tree/main/skills/web-to-markdown

只把 skill 加進去還不夠；如果你的機器無法執行 web2md，或無法啟動 Chrome / Chromium / Brave / Edge，一樣跑不起來。這個本機瀏覽器需求，是最值得最早先確認的導入阻礙。

先讀這兩個檔案最有效率

這個 skill 體積不大，最佳閱讀順序是：

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 印到 stdout
  • 用 --out ./file.md 輸出到單一檔案
  • 用 --out ./some-dir/ 輸出到資料夾
• 有需要時再補充瀏覽器控制參數：
  • 若瀏覽器偵測失敗，使用 --chrome-path <path>
  • 若遇到登入牆、同意畫面或人工驗證，使用 --interactive

如果你沒有明講要怎麼輸出，agent 就得自行猜測。這種不必要的模糊，往往也是最容易提早說清楚的地方。

明確呼叫的要求是硬規則

這個 web-to-markdown skill 只有在使用者明確寫出類似以下內容時才應觸發：

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

如果你是在測試這個 skill，請直接把名稱講出來。這不是可有可無的 repository 使用禮節，而是核心執行邏輯的一部分。

把模糊需求改寫成高成功率提示

弱的請求：

• 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

好的提示能降低失敗率，因為它會直接告訴 skill：

• 要處理哪些頁面
• 輸出要放到哪裡
• 是否可能需要瀏覽器互動
• 這是一筆一次性的工作，還是批次作業

實際值得指定的 command 模式

常見且實用的 web-to-markdown 使用模式包括：

• 單頁輸出到終端：--print
• 單頁輸出到檔案：--out ./page.md
• 多頁輸出到資料夾：--out ./pages/
• 難處理頁面使用可見瀏覽器：--interactive
• 明確指定瀏覽器執行檔路徑：--chrome-path <path>

依照 repository 提供的這些模式來下指令，通常會比開放式地說「幫我抓這個網站」更有用，因為後者的範圍其實已經超出這個 skill 的設計。

單一頁面的最佳工作流程

成功率高的流程通常是：

1. 先確認使用者有明確呼叫 web-to-markdown
2. 收集 URL
3. 決定輸出是要印出還是存檔
4. 只有在頁面真的需要人工協助時才使用 --interactive
5. 檢查 Markdown 結果有沒有漏掉段落，或夾帶太多導覽雜訊
6. 如果擷取不完整，再用更合適的瀏覽器設定重跑一次

這通常比一開始就把 prompt 設計得過度複雜還快。

多個 URL 的最佳工作流程

如果是批次作業：

1. 提供一串 URL 給 skill
2. 選好輸出資料夾
3. 預期存到資料夾時，檔名會由頁面標題衍生
4. 在大批量執行前，先抽查幾個輸出結果

做批次的主要原因是為了維持一致性；最大的風險則是誤以為同一個網站上的每一種頁面樣板都能同樣順利被擷取。

常見的本機環境阻礙

多數 web-to-markdown 安裝失敗，不是 prompt 寫得不好，而是本機環境有問題：

• web2md 沒安裝，或不在 PATH 上
• 本機沒有可用的支援瀏覽器
• 瀏覽器自動偵測失敗，因此需要 --chrome-path
• 頁面需要打開可見瀏覽器並由人手動互動

如果你想快速驗證是否值得導入，建議先測一個公開文章頁，再測一個重度依賴 JS 的頁面，然後再決定要不要放進正式流程。

對輸出品質要有正確期待

web-to-markdown 的目標是乾淨的主內容 Markdown，而不是像素級還原原始頁面。因此代表：

• 文章與文件主體通常會保留得不錯
• header、footer、廣告和頁面外框通常會被弱化
• 特殊 widget、應用程式殼層、嵌入式工具不一定能漂亮轉換

對封存與分析來說，這種取捨通常是加分，但在安裝前先知道，能避免期待落差。

web-to-markdown skill 常見問題

web-to-markdown 會比一般 prompt 更好嗎？

如果你的真正需求是「把渲染後的頁面轉成可用內容」，答案是會。一般 prompt 可以討論某個 URL，但它不會天然幫你打開瀏覽器、等待 JavaScript、擷取可讀主體，再輸出 Markdown。web-to-markdown 的價值，就在於它把這整套流程真正落地執行。

web-to-markdown 適合新手嗎？

適合，前提是你的任務夠單純：一個 URL、一個輸出檔、頁面結構也不複雜。新手最常遇到的難點是本機環境設定，不是 skill 本身太難理解。只要你能跑本機瀏覽器自動化 CLI，這個 skill 就不算難上手。

web-to-markdown 能處理重度 JavaScript 頁面嗎？

這正是它存在的主要理由之一。它透過 Puppeteer 使用真正的本機瀏覽器，因此相較於只抓原始內容的 fetch 型做法，更適合處理 JS 渲染頁面。

web-to-markdown 能穿過登入或驗證畫面嗎？

有時可以，搭配 --interactive。repository 明確支援一種模式：把 Chrome 顯示出來並暫停，讓使用者完成必要的人工作業。對受保護或半受保護頁面來說，這是很實際的優勢。

什麼時候不該用 web-to-markdown skill？

以下情況就不該用：

• 使用者沒有明確指定 web-to-markdown
• 其實用簡單抓頁方式就能完成任務
• 你需要的是跨多個頁面元件的結構化 scraping
• 你想走非瀏覽器式的轉換流程

這個 skill 很專門，而這種專門化是它的優勢，不是缺點。

它支援任何瀏覽器嗎？

文件中明確適配的是 Chromium 系列瀏覽器，例如 Chrome、Chromium、Brave 或 Edge，並透過 puppeteer-core 執行。如果自動偵測失敗，就要準備手動提供路徑。

這個 skill 只適合文章頁嗎？

不是。文章頁是最容易成功的類型，但 web-to-markdown 也很適合文件頁，以及其他以內容主體為主的頁面，只要「擷取主要內容」符合你的輸出目標即可。相對地，它就比較不適合 dashboard 或高度互動式 app。

如何把 web-to-markdown skill 用得更好

為 web-to-markdown 明確指定輸出方式

比起只說「轉這個 URL」，更好的請求是直接說：

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

這樣可以拿掉猜測空間，也更容易讓第一次執行就符合你的實際工作流程。

只有真的需要時才用 interactive mode

--interactive 很適合同意畫面、登入流程和驗證提示，但它比較慢，也較不利於自動化。一般公開頁面能不用就別用；如果頁面本來就有阻擋，反而應該早一點用，不要盲目重試。

先確認瀏覽器偵測是否正常

如果第一次執行時連瀏覽器都打不開，不要一直改 prompt。應該先修正執行環境：

• 確認本機有 Chromium 系列瀏覽器
• 必要時提供 --chrome-path <path>

對很多使用者來說，這是 web-to-markdown 安裝時最重要的一條建議。

大量導入前，先挑代表性頁面測試

在你要轉幾百個 URL 之前，先測：

• 一個簡單的文章頁
• 一個 JS 渲染頁
• 一個有同意或登入阻礙的頁面

這樣測出來的，才是這個 skill 是否適合你的實際網站組成，而不是只看它在理想情況下跑得順不順。

用頁面特性補強 prompt

如果你知道某個頁面特別麻煩，就直接說清楚：

• 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 多半是靠一次有方向的重試改善效果，不是靠長篇推測式 prompt 慢慢試出來。

先認清 web-to-markdown 的主要失敗模式

常見失敗模式包括：

• 沒有明確觸發語句，因此這個 skill 根本不應執行
• 本機瀏覽器啟動有問題
• 頁面需要可視互動
• 頁面的「主內容」對 Readability 而言不夠明確
• 使用者期待的是全站 scraping，而不是頁面轉換

越早辨識這些情況，越能判斷要不要繼續用 web-to-markdown，還是該直接換工具。

把 web-to-markdown 用在對的輸出標準上

當你的成功標準是以下幾件事時，web-to-markdown 通常表現最好：

• 乾淨、可讀的 Markdown
• 內容主體優先，而不是頁面外框
• 可攜式輸出，便於筆記、封存、分析或後續 AI 處理

如果你的成功標準是「保留每一個版面細節」，那這個 skill 就不是對的工具。讓期待與設計目標對齊，往往是改善結果最快的方法。