Book a call
← All skills

Research · Web

Firecrawl Search

Wire Firecrawl's /search into product code as the discovery step before extraction — plus the routing rule people get wrong most: Firecrawl once you know the site, Exa when the source still has to be found.

Skill name
firecrawl-build-search
Triggers on
Integrate Firecrawl `/search` into product code and agent workflows. Use when an app needs discovery before extraction, when the feature starts with a query instead of a URL, or when the system should search the web and optionally hydrate result content.
Read time
4 min · Markdown · free to use and edit
Download .md

Use it in your assistant

Claude Code — drop the file in your skills folder and it loads on the next session. Use ~/.claude/skills for every project, or .claude/skills inside a repo to keep it to that project.

mkdir -p ~/.claude/skills/firecrawl-build-search
curl -L https://growsteady.io/skills/firecrawl-build-search/download -o ~/.claude/skills/firecrawl-build-search/SKILL.md

Claude apps (web and desktop) — Settings → Capabilities → Skills → add a skill. Upload the file as SKILL.md inside a folder named firecrawl-build-search (zip the folder if an archive is asked for).

No install— paste the file into a Claude Project's custom instructions with “Copy as prompt”. Same behaviour, scoped to that project.

Use this when the application starts with a query, not a URL.

Onboarding — start here

1. What this does

Turns a query into a ranked shortlist of real URLs, optionally with their content hydrated in the same call. It is the discovery step that runs before extraction: query → URLs → (/scrape or /interact) → data.

2. Firecrawl or Exa? — the routing rule

This is the decision people get wrong most often, and it costs both money and result quality. The split is about how well-specified the target is:

SituationToolWhy
You know the URLFirecrawl /scrapePrecise and cheap. No search needed at all.
You know the domain, want many pagesFirecrawl crawl / mapEnumerates and reads a site you can already name.
You know the site type — "pricing pages of these 40 companies", "this docs site"Firecrawl /search (this skill)Keyword-shaped, target well-specified.
You do not know where the answer livesExaSemantic discovery. Finds the source before anything can read it.
"Who else does X?", obscure topics, look-alike companiesExaFirecrawl will return the obvious pages; Exa finds the non-obvious ones.

Said plainly: Firecrawl is superior once you know the website. Exa excels at finding hard-to-find websites. Firecrawl is precise and cheap on a known target; ask it to go hunting for an obscure source and it returns the popular answer, not the right one.

The two compose, and that is usually the best pipeline: Exa to find the sources, Firecrawl to read them thoroughly. Reach for Exa first only when the target genuinely has to be located. If you can already name the site, skipping Exa saves a step and a charge.

See exa-search for the other half of this split.

3. Which Firecrawl skill?

You haveYou wantSkill
A queryFind the pages`firecrawl-build-search` (this one)
A URLRead that pagefirecrawl-build-scrape
A URL + the page needs clicks, forms, pagination, loginDrive the pagefirecrawl-build-interact
Nothing set up yetKey + SDK into the projectfirecrawl-build-onboarding
A programming questionIssues, PRs, real docsfirecrawl-developer-index
A research questionPapersfirecrawl-research-index

4. What it can't do

It finds and ranks pages — it is not a crawler (a whole site → crawl/map), not a browser (clicks, forms, auth → firecrawl-build-interact), and not an answer engine: it returns sources, not a synthesized conclusion. It also will not reliably surface a source that is semantically related but keyword-distant from your query — that is the Exa case above.

5. Setup

echo 'FIRECRAWL_API_KEY=your_key_here' >> local.env
set -a && . ./local.env && set +a

Self-hosted deployments set FIRECRAWL_API_URL as well. Never hardcode the key in a script. If nothing is set up yet, run firecrawl-build-onboarding first — it handles the auth flow and SDK install.

6. Verify it works

curl -sS -X POST "https://api.firecrawl.dev/v2/search" -H "Content-Type: application/json" -H "Authorization: Bearer $FIRECRAWL_API_KEY" -d '{"query":"firecrawl docs","limit":3}'

Expect JSON with a result list. A 401 means the key is wrong or not loaded; an empty $FIRECRAWL_API_KEY means step 5 did not take.

7. Cost

Firecrawl bills per request, and hydrating result content costs more than returning URLs alone. Prefer selective follow-up extraction over broad hydration. Before running search in a loop over many rows, estimate the call count and tell the user what the run costs.

8. Read next

Default Recommendations for the shape of a good integration, Escalation Rules for when to hand off, and your language's page under Docs (Source of Truth) before writing integration code.

Use This When

  • the user asks a question and the product must discover sources first
  • the feature needs current web results
  • you want to turn a search query into a shortlist of pages for later scraping

Default Recommendations

  • Use /search first when URL discovery is part of the product behavior.
  • Keep search and extraction conceptually separate unless scraping search results is clearly required.
  • Prefer selective follow-up extraction over broad hydration when cost or latency matters.

Common Product Patterns

  • answer generation with cited sources
  • company, competitor, or topic discovery
  • research workflows that produce a shortlist before deeper extraction
  • query-to-URL pipelines for later /scrape or /interact

Escalation Rules

Implementation Notes

  • Treat /search as discovery, ranking, and source selection.
  • Be explicit about whether the product needs snippets, URLs, or full result content.
  • Keep the query contract stable so downstream scraping logic stays predictable.

Docs (Source of Truth)

Read the source-of-truth page for your project language before writing integration code:

See Also

← All skills