firecrawl-agent

firecrawl-agent skill 概覽

firecrawl-agent 的功能

firecrawl-agent skill 適合用在一般單頁抓取不夠用的自主式網頁資料擷取情境。它的設計重點是能自行瀏覽網站、判斷相關資訊位於哪些頁面，並回傳結構化 JSON，特別適合價格方案表、商品目錄、名錄條目與功能清單這類工作。

最適合的使用者

這個 firecrawl-agent skill 最適合需要可直接使用的資料，而不是原始 HTML 的人：建立資料集的營運或資料工作者、蒐集競品或市場資訊的分析人員、要把資料送進下游自動化流程的開發者，以及希望做多頁擷取並輸出 schema 化結果，而不是臨時複製貼上的 AI 使用者。

真正要解決的工作

大多數使用者其實不是在抽象地找「web scraping」。他們真正想回答的是更具體的問題，例如：

• 擷取 SaaS 官網上的所有價格方案層級
• 跨多個頁面收集商品名稱與價格
• 把網站名錄整理成 JSON records
• 不用手動對每個 URL 做 mapping，也能收集結構化事實資料

這正是 firecrawl-agent for Web Scraping 與一般泛用 prompt 有明顯差異的地方。

為什麼選 firecrawl-agent，而不是單純用 prompt

一般模型 prompt 可以幫你建議 selectors，或摘要目前看得到的頁面內容，但通常無法穩定處理跨多頁的自主式擷取流程。firecrawl-agent 就是為這種情境打造：給它一個擷取目標，視需要補上 schema，接著讓它自行導覽並回傳機器可用的輸出。

安裝前先知道的主要取捨

它的優點是能大幅減少逐頁手動處理的工作量。代價則是執行時間：agent 可能需要幾分鐘，而且輸出品質非常依賴你是否清楚定義目標欄位與範圍。如果你的需求只是「快速抓單一頁面」，那它可能比你實際需要的更重一些。

如何使用 firecrawl-agent skill

firecrawl-agent 的安裝前提

上游 skill 允許透過 Bash 使用 firecrawl，包含 firecrawl agent 與 npx firecrawl。如果你要把它安裝到 skills-based environment，請使用：

npx skills add https://github.com/firecrawl/cli --skill firecrawl-agent

實務上，你也需要讓 Firecrawl CLI 能在目前環境中使用，並完成該 CLI 所需的驗證或其他初始化設定。

先讀這個檔案

請先從 skills/firecrawl-agent/SKILL.md 開始看。就這個 repository 而言，這個檔案幾乎包含了所有實際可用的指引。這個 skill 看起來沒有明顯的 rules/、resources/ 或輔助 scripts，因此是否安裝，主要就要看其中的範例與 CLI 選項是否符合你的工作流程。

先理解主要呼叫模式

核心的 firecrawl-agent usage 模式其實很單純：

1. 描述擷取目標
2. 視需要提供 schema
3. 視需要用起始 URLs 限制範圍
4. 等待工作完成
5. 將 JSON 輸出存成檔案

此 skill 中常見的範例如下：

firecrawl agent "extract all pricing tiers" --wait -o .firecrawl/pricing.json

firecrawl agent "extract products" --schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' --wait -o .firecrawl/products.json

firecrawl agent "get feature list" --urls "<url>" --wait -o .firecrawl/features.json

這個 skill 需要哪些輸入

firecrawl-agent skill 在以下三件事都明確提供時，效果通常最好：

• 擷取目標
• 網站或起始 URLs
• 你希望輸出的資料形狀

較弱的輸入：

• 「scrape this site」

較強的輸入：

• 「Extract all pricing tiers from https://example.com/pricing and related plan pages. Return plan name, monthly price, annual price, included seats, and top features as JSON.」

最佳輸入：

• 「Starting from https://example.com/pricing, extract every current pricing tier visible on the site. Return JSON with plans[] containing name, billing_period, price, currency, seat_limit, features[], and source_url. Ignore blog pages, docs, and historical changelog content.」

什麼情況下要用 schema

當你的輸出要餵給程式、試算表、驗證流程或可重複執行的工作流時，就應該使用 --schema。schema 特別重要的情況包括：

• 欄位名稱必須維持穩定
• 你需要像數字或陣列這類具型別的值
• 你想減少模糊或不一致的摘要
• 你打算比較不同執行結果或不同網站的輸出

不使用 schema，agent 仍然可能表現不錯，但對下游自動化來說，結果通常會比較不穩定。

如何把模糊需求改寫成好 prompt

一個好的 firecrawl-agent guide prompt，通常會包含：

• 目標實體類型：plans、products、listings、locations
• 覆蓋規則：要抓所有目前有效的項目，不是只抓範例
• 排除條件：忽略 docs、blog、careers、changelog
• 正規化規則：價格回傳為數字、每個項目一筆 record
• 來源資訊：包含 source_url
• 邊界情況處理：若欄位缺漏，回傳 null

範例：

firecrawl agent "Extract all products from the site. Return JSON with products[] containing name, price, currency, short_description, category, availability, and source_url. Only include live product pages. Ignore blog, support, and policy pages. If price is missing, use null." --urls "https://example.com" --wait -o .firecrawl/products.json

用起始 URLs 降低偏移

如果你完全不提供 URLs，agent 就有更大的空間自行決定要探索哪些位置。這有時很有幫助，但也更容易把時間浪費在不必要的導覽上。若想提高精準度，建議先提供高機率命中的入口頁，例如：

• pricing pages
• product category pages
• company directories
• marketplace listings

這是提升 firecrawl-agent install 成功率時，實務上最有槓桿效果的做法之一。

建議的可靠擷取流程

一個務實的工作流程如下：

1. 先針對單一高可能性的來源頁做小範圍測試
2. 檢查 JSON 是否有欄位遺漏或欄位被錯誤合併
3. 加上 schema 與排除條件
4. 再擴大到更廣的起始 URLs
5. 將輸出存到固定資料夾，例如 .firecrawl/
6. 驗證數量並抽查來源頁面

和一開始就大範圍執行、事後再回頭清 noisy 結果相比，這樣通常更快。

輸出處理與檔案策略

使用 -o 將結果寫到固定且可預期的路徑。原因是自主式擷取工作若要評估品質，最好能把輸出做版本管理，或在不同時間點進行比對。常見的好例子包括：

• .firecrawl/pricing.json
• .firecrawl/products.json
• .firecrawl/directory.json

如果你正在反覆調整，檔名應該清楚反映每次執行的目的，而不是一直覆蓋一個籠統的 output.json。

實務適配：firecrawl-agent 最擅長什麼

firecrawl-agent for Web Scraping 最強的使用情境是：

• 目標資料分散在多個頁面
• 事前不完全清楚網站結構
• 你需要的是結構化 JSON，而不是自然語言敘述
• 手寫 scraping 規則所花的時間，比這次擷取任務本身還不划算

實務不適配：什麼情況不建議用

以下情況建議跳過 firecrawl-agent：

• 你只需要摘要單一頁面
• 合規要求很高，必須使用完全可決定、可重現的 selectors
• 你已經有穩定可用的 scraper，且頁面結構已知
• 網站高度互動、有存取門檻，或依賴你目前環境不支援的 session-specific flows

firecrawl-agent skill 常見問題

firecrawl-agent 適合初學者嗎？

適合，前提是你已經會使用 CLI，並且能用輸出欄位的方式思考需求。基本範例不難上手。對初學者來說，真正的門檻通常不是安裝語法，而是不知道如何把擷取目標描述完整，而只是提出很模糊的要求。

firecrawl-agent 和一般 AI prompting 有什麼不同？

一般 prompt 往往只停留在分析或一次性的頁面內容整理。firecrawl-agent usage 的核心則是自主式網站導覽加上結構化擷取。這個組合，正是你應該使用這個 skill，而不是只下「summarize this website」這類泛用指令的原因。

我每次都需要 JSON schema 嗎？

不需要。若只是探索性工作，單純的擷取要求可能就夠了。但如果你需要跨次執行的一致性、自動化能力，或乾淨且具型別的欄位，schema 通常值得你多花那一分鐘補上。

firecrawl-agent 需要跑多久？

skill 內提到，自主式擷取大約可能需要 2 到 5 分鐘。和簡單的單頁抓取相比，請預期它會花更久，尤其是在網站包含許多相關頁面時。

firecrawl-agent 能擷取價格、商品或名錄嗎？

可以。這些正是這個 skill 的主要定位：價格方案層級、商品列表、directory-style 條目，以及其他分散在網站各處的結構化 records。

firecrawl-agent 適合所有 scraping 工作嗎？

不適合。如果任務本身很簡單、完全可決定，或早就能由傳統 scraper 穩定處理，那這個 skill 可能沒有必要。它最有價值的地方，在於「發現該去哪裡找資料」與「跨頁導覽」本身就是問題的一部分。

如何改進 firecrawl-agent skill 的使用效果

給 firecrawl-agent 更清楚的擷取契約

品質提升幅度最大的方法，通常是把 prompt 從「extract data」升級成一份明確契約，內容包括：

• 精確欄位
• 納入規則
• 排除規則
• 缺值處理方式
• source URL 紀錄

這能降低憑空補出的結構，也讓結果更值得信任。

先收斂範圍，再擴大覆蓋

很多不理想的結果，都是因為從網域首頁搭配寬鬆目標直接開始。更好的做法是先從一到兩個高訊號 URL 起步，確認欄位品質，再等 schema 與 prompt 都穩定後才擴大範圍。

每筆資料都要求保留來源資訊

如果你打算審查或除錯結果，請要求每筆項目都包含 source_url。單是這個欄位，就能讓 firecrawl-agent guide 的工作流程輕鬆很多，因為你可以快速核對每一筆擷取結果是否真的來自正確頁面。

正規化那些最容易變動的欄位

你應該明確告訴 agent，真實世界中常見的資料變化要怎麼處理：

• price 要用 numbers 還是 strings
• monthly 與 annual billing 怎麼表示
• feature list 要用 arrays
• 缺漏欄位以 null 表示
• 每個 product 或 plan 只對應一筆 record

這些指示能實質提升機器可讀性。

留意常見失敗模式

常見問題包括：

• 同一份資料集混入不同類型的頁面
• 因變體頁面而出現重複 records
• feature summaries 被合併成一整塊文字
• prices 被抓成文字片段，而不是數值
• 起始點過廣或過弱，導致網站覆蓋不完整

大多數這類問題，解法不是重跑同一個模糊指令，而是把範圍與 schema 設計得更清楚。

依輸出缺陷迭代，不要只看頁面數量不夠

如果第一次執行結果不對，不要只是要求「更多 pages」。先找出真正的缺陷：

• 欄位不對
• 頁面類型不對
• 有重複
• 缺少正規化
• 覆蓋範圍不完整

然後直接針對這個缺陷改寫 prompt。這通常是改善 firecrawl-agent 結果最快的方法。

一個有效的二次修正模式

實用的第二輪 prompt 修正方式通常是：

• 保留相同目標
• 補上排除條件
• 收緊欄位定義
• 要求保留來源資訊
• 定義缺值處理方式

修正範例：

• first run: “extract all pricing tiers”
• second run: “Extract all current pricing tiers from pricing and plan pages only. Ignore docs, blog, changelog, and legacy pages. Return plans[] with name, price, currency, billing_period, features[], and source_url. Use null when a field is not present.”

先檢查一件事，幫助你判斷 firecrawl-agent 是否值得安裝

在採用 firecrawl-agent skill 之前，先問自己：你真正的瓶頸，是不知道該去哪幾頁找資料，還是只是需要把既有內容整理成固定格式？如果瓶頸是多頁網站中的導覽與發現，那這個 skill 很適合；如果不是，更簡單的 scrape 或單頁擷取工具通常會更快，也更容易維護。