firecrawl-crawl

Visão geral da skill firecrawl-crawl

O que a firecrawl-crawl faz

A skill firecrawl-crawl foi feita para extração em massa de sites, não para scraping de uma única página. Ela ajuda um agente a rastrear um site ou uma seção específica, seguir links e retornar conteúdo de várias páginas em uma única execução. Se o seu objetivo é “pegar todas as páginas de documentação”, “extrair tudo em /docs” ou “rastrear esta central de ajuda até profundidade 3”, esta é a ferramenta certa.

Para quem a firecrawl-crawl é indicada

A firecrawl-crawl é mais indicada para quem precisa coletar conteúdo de múltiplas páginas para análise de documentação, migração, indexação, QA, pesquisa ou ingestão de conhecimento. Ela é especialmente útil quando um prompt comum seria manual demais, porque o conteúdo-alvo está espalhado por dezenas de páginas interligadas no mesmo domínio.

O trabalho real que ela resolve

As pessoas adotam a firecrawl-crawl quando precisam de cobertura, não apenas de precisão em uma URL isolada. O principal desafio é definir com clareza o limite do crawl para que a ferramenta colete as páginas certas sem perder tempo com seções irrelevantes, duplicações ou com o site público inteiro.

O que diferencia esta skill

Os principais diferenciais estão nos controles práticos de crawl: filtragem por caminho, limites de profundidade, limite de páginas, execução assíncrona e comportamento opcional de espera/progresso. Isso faz da firecrawl-crawl for Web Scraping uma opção mais operacional do que uma instrução genérica como “faça scraping deste site”.

Quando esta skill é uma ótima escolha

Use a firecrawl-crawl skill quando:

• você precisa de muitas páginas de um mesmo site
• as páginas podem ser descobertas por links internos
• você quer limitar o escopo com caminhos como /docs, /blog ou similares
• você precisa de um comando de crawl reproduzível, e não de prompts ad hoc

Quando não usar

Não comece com a firecrawl-crawl se você só precisa de uma página, precisa primeiro de um inventário de URLs ou ainda não sabe qual seção importa. Nesses casos, etapas mais simples de search, scrape ou map costumam funcionar melhor antes de partir para crawl.

Como usar a skill firecrawl-crawl

Contexto de instalação da firecrawl-crawl

Esta skill faz parte do conjunto firecrawl/cli e foi pensada para ser invocada via ferramentas do Firecrawl CLI. Se o seu ambiente oferece suporte a Skills, o padrão prático de instalação é:

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

Você também precisa ter o Firecrawl CLI disponível para que o agente possa executar comandos como firecrawl crawl ou npx firecrawl crawl.

Leia este arquivo primeiro

Comece por skills/firecrawl-crawl/SKILL.md. Para esta skill, esse arquivo concentra grande parte do valor operacional: quando usar, comandos de início rápido e as principais opções que controlam o escopo do crawl e o comportamento em tempo de execução.

Padrões principais de comando

O repositório mostra três padrões centrais de firecrawl-crawl usage:

# Crawl a docs section
firecrawl crawl "<url>" --include-paths /docs --limit 50 --wait -o .firecrawl/crawl.json

# Full crawl with depth limit
firecrawl crawl "<url>" --max-depth 3 --wait --progress -o .firecrawl/crawl.json

# Check status of a running crawl
firecrawl crawl <job-id>

Eles cobrem a maioria dos fluxos reais: crawl restrito a uma seção, crawl mais amplo do site com controle de profundidade e consulta de um job já em execução.

Entradas que mais importam

Para obter bons resultados com a firecrawl-crawl, informe:

• uma URL inicial limpa
• a seção desejada do site, se houver
• um limite de páginas sensato com --limit
• um limite de profundidade com --max-depth quando o site for amplo
• se você quer conclusão síncrona com --wait
• um caminho de saída para facilitar a inspeção posterior

A principal alavanca de qualidade é o escopo do crawl. Um bom limite quase sempre importa mais do que qualquer processamento posterior.

Como transformar um pedido vago em um prompt forte

Pedido fraco:

• “Faça crawl deste site e pegue tudo.”

Pedido melhor:

• “Use firecrawl-crawl em https://example.com, restrinja a /docs, limite a 50 páginas, espere a conclusão, salve a saída em .firecrawl/crawl.json e resuma as principais páginas de configuração do produto após a extração.”

Por que isso funciona:

• cita a skill
• fornece uma URL inicial
• restringe o caminho
• limita custo e tempo de execução
• deixa claro o que deve acontecer após o crawl

Melhor fluxo para a primeira execução

Um firecrawl-crawl guide prático para o primeiro uso:

1. Escolha a URL inicial mais específica que ainda faça sentido.
2. Adicione --include-paths se você só precisa de uma seção.
3. Defina --limit de forma conservadora na primeira rodada.
4. Adicione --max-depth se o site tiver muitas ramificações.
5. Use --wait em execuções simples, ou envie o job e consulte depois em crawls maiores.
6. Salve a saída com -o para revisar o que foi coletado de fato.

Essa sequência reduz crawls desperdiçados e facilita ajustar os limites depois do primeiro resultado.

Controles de escopo que evitam crawls ruins

As opções mais importantes destacadas na skill são:

• --include-paths para manter o crawl na seção certa
• --limit <n> para evitar contagens de páginas fora de controle
• --max-depth <n> para impedir travessias profundas demais
• --wait para bloquear até a conclusão
• --progress para acompanhar o andamento durante a espera

Se você ignorar esses controles, um crawl pode ficar amplo demais mais rápido do que parece, especialmente em sites de documentação com changelogs, links para blog ou navegação muito interligada.

Modo assíncrono vs modo de espera

Use --wait quando quiser um fluxo em uma única etapa e o crawl precisar terminar agora. Ignore essa opção quando o crawl puder demorar mais e você preferir um fluxo baseado em jobs. O repositório dá suporte explícito à verificação posterior de status com firecrawl crawl <job-id>, o que é útil em jobs maiores ou em fluxos de agentes que separam envio e análise.

Saída, revisão e validação

Em execuções sérias, sempre grave em arquivo, por exemplo:

firecrawl crawl "https://example.com" --include-paths /docs --limit 50 --wait -o .firecrawl/crawl.json

Isso facilita a revisão após a execução. Antes de pedir ao agente para resumir ou transformar os resultados, verifique se a saída contém a seção pretendida e a quantidade esperada de páginas. Limites de crawl mal definidos geram sínteses ruins depois.

Bons padrões de uso da firecrawl-crawl

Casos de alto valor incluem:

• coletar todas as páginas de documentação para uma comparação de produtos
• extrair uma seção de central de ajuda para busca interna ou preparação de RAG
• puxar um conjunto de guias de migração antes de reescrever documentação
• fazer bulk-scraping de uma seção conhecida de um site em que os links já conectam as páginas relevantes

Esses cenários combinam muito mais com a ferramenta do que “encontre qualquer coisa interessante neste domínio”.

FAQ da skill firecrawl-crawl

A firecrawl-crawl é amigável para iniciantes?

Sim, desde que você já entenda a diferença entre scraping de uma página e crawling de múltiplas páginas. A superfície de comandos é pequena, mas quem está começando deve partir de um caminho restrito e um limite baixo de páginas para evitar execuções grandes demais.

Qual é a diferença entre firecrawl-crawl e um prompt comum?

Um prompt simples pode descrever o objetivo, mas a firecrawl-crawl oferece ao agente um caminho operacional definido: enviar um job de crawl, controlar profundidade e limites, opcionalmente esperar e salvar uma saída estruturada. Isso reduz tentativa e erro e torna execuções repetidas mais consistentes.

Quando devo usar firecrawl-crawl em vez de scrape?

Use firecrawl-crawl quando o conteúdo-alvo estiver distribuído por muitas páginas interligadas. Use scrape quando você só precisa de uma URL conhecida. Se você ainda não sabe quais páginas importam, map ou search pode ser uma etapa melhor antes de partir para crawl.

A firecrawl-crawl serve bem para extração de site inteiro?

Às vezes, mas só se você puder lidar com uma cobertura ampla e tiver bons limites definidos. Em sites grandes, “site inteiro” costuma ser uma péssima primeira execução. Na prática, fazer crawl de uma subseção de docs geralmente é mais útil do que começar pela homepage com controles frouxos.

A firecrawl-crawl funciona bem para seções de documentação?

Sim. Os exemplos do repositório destacam explicitamente extração por seção, como /docs, que é um dos casos de uso mais fortes de firecrawl-crawl for Web Scraping.

O que costuma atrapalhar bons resultados?

Os bloqueadores mais comuns são escopo vago, ausência de filtros de caminho, falta de limite de páginas e URL inicial errada. Esses detalhes não são secundários; eles determinam diretamente se a saída será útil ou ruidosa.

Como melhorar a skill firecrawl-crawl

Defina limites mais precisos para o crawl

A forma mais rápida de melhorar a saída da firecrawl-crawl é definir o limite do crawl com precisão. Informe a URL inicial, o caminho da seção, o limite de páginas e a profundidade desejada. “Faça crawl da documentação em /docs até 2 níveis de profundidade” é muito melhor do que “faça crawl do site”.

Comece pequeno e só depois expanda

Para uma adoção melhor e menos execuções desperdiçadas, faça primeiro um crawl pequeno de validação:

• --limit baixo
• --include-paths restrito
• --max-depth moderado

Se a saída parecer correta, aumente o limite. Isso ajuda a capturar erros de escopo antes que virem custo alto ou execução lenta.

Escreva prompts que incluam a tarefa pós-crawl

firecrawl-crawl install é só uma parte do sucesso. Diga também ao agente o que fazer depois da extração. Exemplo:

• “Use firecrawl-crawl para extrair /docs até 50 páginas, salve em .firecrawl/crawl.json e depois identifique páginas de onboarding, auth e referência de API.”

Isso melhora a utilidade de ponta a ponta porque crawl e análise já saem alinhados desde o início.

Evite modos de falha comuns

Problemas frequentes com a firecrawl-crawl skill:

• começar pela homepage quando só uma seção é necessária
• omitir --limit em um site grande
• omitir --max-depth quando a navegação é densa
• esquecer -o e perder um ponto simples de revisão
• pedir “tudo” sem definir relevância de negócio

Itere com base na saída, não em suposições

Depois da primeira execução, inspecione o que de fato foi coletado. Se páginas irrelevantes estiverem dominando, restrinja mais o --include-paths ou reduza a profundidade. Se páginas importantes estiverem faltando, aumente a profundidade ou comece por um ponto de entrada mais relevante. O melhor firecrawl-crawl guide é iterativo: fazer crawl, inspecionar, refinar e rodar de novo.

Mantenha a firecrawl-crawl no papel certo

Use a firecrawl-crawl para coleta e depois passe para etapas de sumarização, classificação, comparação ou indexação. Tentar fazer a etapa de crawl resolver todas as tarefas posteriores de uma vez geralmente reduz a clareza. A skill é mais forte quando primeiro reúne o corpus certo.