Preface¶

When adding “web data fetching” capabilities to an Agent or backend, the common bottleneck is not whether you know how to make HTTP calls, but having to re-decide every time: should I directly scrape an already known URL, or first search for it? What if content is only revealed after clicking buttons or filling out forms on a page? Where to store API keys, which SDK to use, and how to verify that the entire request链路 actually works? Documentation is scattered across various language SDKs, and it’s easy for Agents to confuse “help me search within the current session” with “incorporate Firecrawl into production code”.

Firecrawl’s official team has packaged the latter path into an Agent Skill. The repository firecrawl/skills targets “calling the Firecrawl API within an application”, with the entry skill being firecrawl-build: it first asks the product what data needs to be fetched from the web and how, then routes the request to /scrape, /search, or /interact, instead of letting the model invent a scraping workflow on the spot.

This article cross-checks against the Skill’s SKILL.md, the repository README, and docs.firecrawl.dev/ai-onboarding to explain what this Skill is, what capabilities it covers, how to install it, and its boundary with the CLI Skill.

What It Is¶

firecrawl-build is the application integration entry Skill maintained by Firecrawl, located at skills/firecrawl-build/ in github.com/firecrawl/skills. The current metadata version is 0.1.0, licensed under ISC, with the homepage at firecrawl.dev. The repository follows the SKILL.md format specified by Agent Skills and is provided as a plugin for Claude Code, Cursor, and OpenAI Codex.

The official one-sentence positioning is: when a product, Agent, or workflow needs to obtain web page data within an application—including search, real-time retrieval results, page scraping, structured extraction, or browser interaction—connect Firecrawl to your code. This Skill should be used even if the user does not explicitly name Firecrawl, but only mentions “need web content/search/scraping/interaction in the application”.

It solves routing and implementation issues, rather than replacing SDK documentation. As clearly stated in SKILL.md: these Skill descriptions explain when and why to use a specific endpoint; the actual calling method should refer to the source-of-truth pages for each language.

Core Capabilities¶

1. Select the Endpoint First, Then Write Integration Code¶

The entry skill requires answering one question first: What data does this product need to get from the web, and how? Then select the most appropriate endpoint:

The default priority is: /scrape first, then /search, and finally /interact. Do not perform a search first when you already know the URL; do not use browser actions when the page can be read directly.

The three official product forms also correspond to these three endpoints:
- Known URL → Extract content: Document import, competitor pricing pages, content injection into retrieval pipelines, use /scrape
- Query → Discover → Extract: Q&A with fresh sources, competitor discovery, research that first generates a shortlist of URLs, use /search; only follow up with scraping when the product truly needs full text
- Scrape → Interact → Extract: Upgrade to /interact only when you need to expand collapsed content, perform form-based searches, page turning, or access background pages that require login status

2. Umbrella Skill, Delegate Details to More Specialized Sub-skills¶

firecrawl-build itself does not elaborate on the implementation details of each endpoint, but instead assigns tasks to specialized skills in the same repository. The actual skills existing in the current skills/ directory are:

The research index and developer index will not be returned by /search. The categories: ["research"] or ["developer"] parameters on /search only filter regular web results by domain name, and do not perform abstract retrieval, related paper expansion, or full-text paragraph recall. When you need indexing capabilities, switch to the corresponding index skill instead of treating /search with a category parameter as a paper database.

Some documentation pages also mention broader APIs such as /crawl, /map, /parse. As far as this firecrawl-build SKILL.md and the current repository directory are concerned, the entry routing table covers the three endpoints plus the two indexing skills; when writing integrations, refer to the skill list in the repository.

3. Related to In-application Integration, Not “Help Me Search Right Now”¶

Officially, Firecrawl’s Agent capabilities are split into three lines, which can all be installed with one command, but must be used separately:
- CLI Skill (firecrawl/cli): Real-time web operations in the current session—search web pages, scrape a single page, interact with sites, crawl entire sites
- Build Skill (this repository): Integrate Firecrawl into application code
- Workflow Skill (firecrawl/firecrawl-workflows): Generate deliverables such as research reports, SEO audits, or lead lists, not production code

The trigger condition for firecrawl-build is “add web data capabilities to an application”, not “help me search/scrape a page now in the terminal”. The latter should use firecrawl/cli.

Installation and Activation¶

The official recommendation is to install all three segments of skills (CLI, Build, and Workflow) with one command and open the browser for login:

npx -y firecrawl-cli@latest init --all --browser

The documentation explains: --all will install the skills for every AI coding agent detected on the local machine; --browser automatically opens Firecrawl authentication. After installation, you need to restart the agent for it to discover these skills. You can use the following two commands to check the installation status:

firecrawl --status
firecrawl scrape "https://firecrawl.dev"

To install only this repository’s application integration skills:

npx skills add firecrawl/skills

To install only the entry skill, the command provided by officialskills.sh is:

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

You can also point the coding assistant to the repository directory and have it install via the Agent Skills process. Claude Code documentation specifies: when using --agent claude-code, the skills will be installed to .claude/skills/ in the current project. Cursor and Codex are provided as .cursor-plugin/ and .codex-plugin/ plugins in the repository README; the exact local installation directory depends on the installation command and the corresponding tool’s documentation, do not guess the path arbitrarily.

If you have already installed the skills and only want to add missing ones later, the CLI documentation provides:

firecrawl setup skills      # CLI + build skills
firecrawl setup workflows   # workflow skills

The repository README also mentions that the plugin comes with configuration for the official Firecrawl MCP server, and editors that support bundled MCP metadata can connect to the tool using FIRECRAWL_API_KEY. This is an additional capability of the plugin, not the calling method of firecrawl-build itself.

API Keys, SDKs, and Integration Sequence¶

The hosted service requires environment variables (do not hardcode them into source code):

FIRECRAWL_API_KEY=fc-...

For self-hosted instances, add this only if you are not using https://api.firecrawl.dev:

FIRECRAWL_API_URL=https://your-firecrawl-instance.example.com

API keys can be obtained at firecrawl.dev/app. If you do not yet have an API key, run firecrawl-build-onboarding first, which comes with browser-based authentication and does not rely on another onboarding skill on the website.

The SDK should match the project’s programming language. For existing projects, first refer to the package manager and existing third-party client configurations before deciding whether to install the SDK or use direct REST calls:

npm install @mendable/firecrawl-js

pip install firecrawl-py

The official also provides source-of-truth pages for Rust, Java, Elixir, as well as cURL/REST. If there is no corresponding SDK for your language, or if your project already has a unified HTTP wrapper, you can use direct REST calls.

The default integration sequence is hardcoded in SKILL.md and should not be skipped:
1. First configure the FIRECRAWL_API_KEY or FIRECRAWL_API_URL pair
2. Determine whether it is a new project or an existing codebase
3. Clarify the product’s required web data behavior, then select the endpoint
4. For existing projects, first understand the existing conventions before making changes
5. Install the corresponding SDK or use REST calls
6. Read the language-specific source-of-truth page before writing code
7. Delegate endpoint details to more specialized skills
8. Perform a real test request for smoke testing, instead of only verifying that the code compiles

New project workflow: Confirm tech stack → Install SDK/configure environment variables → Write minimal working call → Smoke test.
Existing project workflow: First review the language, package manager, directory structure, entry points (routing/worker/tasks), existing network wrappers, and key management, then ask “What will Firecrawl do in this product”, and finally follow the repository conventions to integrate.

Typical Usage¶

The following calling examples come from the official Python source-of-truth (the SDK documentation corresponds to firecrawl-py / firecrawl 4.22.1). The Skill itself emphasizes: parameters and return structures are subject to this page, do not rely on model memory.

First create the client:

import os
from firecrawl import Firecrawl

client = Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))

Already have a URL, scrape a page into Markdown (/scrape, also the minimal request for smoke testing):

doc = client.scrape("https://docs.firecrawl.dev", formats=["markdown"])

Discover pages from a query (/search). Note that the return value has buckets for web/news/images, not { data: [...] }:

results = client.search("site:docs.firecrawl.dev webhook retries")
for item in results.web or []:
    print(getattr(item, "url", None), getattr(item, "title", None))

When further operations are required on the page, first scrape, then use the returned scrape_id to call /interact:

doc = client.scrape("https://example.com", formats=["markdown"])
job_id = doc.metadata.scrape_id if doc.metadata else None
if not job_id:
    raise RuntimeError("Missing scrape_id from scrape response")

result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")

When triggering the entry skill in a conversation, the official typical descriptions include: add web data to the application, add search functionality to the product, scrape pages in a workflow, or enable site interaction in the application. The Agent should first perform intake (new or existing project, where data comes from, how to fetch it), then proceed to the specific endpoint, instead of directly generating a long crawler script.

The smoke test standard is specified in references/verification.md: for new projects, use a minimal request to prove authentication, network connectivity, and SDK connectivity (scrape a known URL with /scrape, or use /search with limit=1, or perform a minimal action on a scrape with /interact); for existing projects, complete a full test through the real entry point (application, worker, or script) and confirm that the key comes from the expected environment source. A successful real request with results flowing into the business path counts as completion.

Applicable Scenarios and Notes¶

Suitable Cases:¶

• Backends, Agent tools, or automated workflows that need to fetch web data from code
• New features that need to choose between “search/scrape/interact” instead of building a custom crawler from scratch
• Need to correctly configure API keys, SDKs, repository conventions, and smoke testing in one go
• Integrating Firecrawl into Node/Python/Go backends (Go can use REST; Node and Python have official SDKs)

Unsuitable Cases, or Should Use Other Skills:¶

• One-time “help me search/help me scrape this page” in the current session — use firecrawl/cli
• Targeting deliverables such as research reports, SEO audits, or lead lists — use workflow skills
• Retrieving papers or developer knowledge bases — use firecrawl-research-index or firecrawl-developer-index respectively, do not treat them as regular /search

Usage Notes:¶

• Do not hardcode API keys. Store them in .env or the deployment platform’s key management system.
• For existing projects, review the repository first before installing dependencies. The Skill requires matching existing package managers and third-party client configurations, instead of setting up a new system for convenience.
• Keep /interact minimal. The official recommendation is to only cover the shortest browser workflow required to unlock the required data; fully open browser automation may be more suitable for a separate browser sandbox rather than hardcoding into /interact.
• Caching and freshness. firecrawl-build-scrape states that Firecrawl will reuse recent indexes, making repeated reads of the same URL faster; use maxAge (in milliseconds) for fresher data, with maxAge: 0 skipping index reuse. The metadata.cacheState / metadata.cachedAt fields in successful responses indicate which copy was actually retrieved.
• Skills are not SDK manuals. Request bodies, response fields, and parameter names are subject to the language-specific page at docs.firecrawl.dev/agent-source-of-truth. For example, Python’s search() result is in result.web, and accessing result.data will be incorrect.
• If documentation conflicts with the repository, use the repository as the source of truth. A few onboarding pages listed non-existent directories such as firecrawl-build-crawl; when integrating, cross-check the skills/ directory on GitHub.

Summary¶

firecrawl-build is the official entry Skill for “adding web data capabilities to production products”: first clarify requirements, then map functions to /scrape, /search, or /interact, and string together API key configuration, SDK setup, repository conventions, and a real smoke test request into a fixed sequence. It shares the installation command with firecrawl/cli but has opposite responsibilities — one modifies product code, the other serves the current session.

Official Links:
- Skill directory: https://github.com/firecrawl/skills/tree/main/skills/firecrawl-build
- Full repository: https://github.com/firecrawl/skills
- Installation documentation mirror: https://officialskills.sh/firecrawl/skills/firecrawl-build
- Agent integration overview: https://docs.firecrawl.dev/ai-onboarding