How to use the Firecrawl Web Search and Scrape agent skill

What is an agent skill, and what does firecrawl-search do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task, and it can include scripts the agent runs. The firecrawl-search skill is one such folder in the Auto-claude-code-research-in-sleep research toolkit, located at skills/firecrawl-search.

Once installed, the agent can search the web through Firecrawl and read each result as full-page markdown, so it can use project pages, blog posts, leaderboards and PDF reports instead of short snippets. The skill also scrapes a specific URL you provide. It is meant for sources outside academic databases; for direct preprint or published-paper searches, the toolkit has separate skills such as /arxiv and /semantic-scholar.

Install the firecrawl-search skill

You can install the skill in either of two ways. Download the ZIP from this page, then either unzip it into ~/.claude/skills/ to make it available across your projects, or unzip it into a project's .claude/skills/ folder to limit it to that project.

Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Set up your Firecrawl API key and helper

The helper script uses only the Python 3 standard library, so there is nothing extra to install for Python. You do need a Firecrawl API key, which you set as an environment variable named FIRECRAWL_API_KEY. You can get a key from firecrawl.dev. Requests without a key are limited to a small daily cap.

The skill also needs the firecrawl_search.py helper from the ARIS repository (tools/ folder). The skill looks for it in .aris/tools/, tools/, the location in the ARIS_REPO environment variable, or the path recorded in ~/.aris/repo. If it cannot find the helper, it stops with an error and suggests rerunning the install scripts, exporting ARIS_REPO, or copying the helper to tools/.

• Python 3 (standard library only)
• FIRECRAWL_API_KEY set in your environment
• firecrawl_search.py from the ARIS repository tools/ folder

How do you trigger the skill with natural requests?

You can invoke the skill with the phrases "firecrawl search", "firecrawl scrape" or "/firecrawl-search". Put your query or URL after the command. The skill accepts a search query, or one or more URLs, which switches it to scrape mode.

A bare URL is scraped instead of searched. Optional overrides go at the end of your request, for example the number of results, whether to include page content, a time range, or a domain filter.

• Search: /firecrawl-search "KV cache compression" — max: 10 (top 10 results)
• Titles and links only: /firecrawl-search "speculative decoding" — content: none
• PDFs only: /firecrawl-search "mixture of experts" — category: pdf
• Past month: /firecrawl-search "diffusion transformers" — time: qdr:m
• Domain filter: /firecrawl-search "LLM agents" — domains: arxiv.org,openreview.net
• Scrape a page: /firecrawl-search "https://arxiv.org/abs/2211.17192"

What does the agent return?

By default the skill searches and returns up to 5 results, each with its markdown content kept to 4000 characters. The agent presents results in a table with the title, source domain, URL, and a short summary of the relevant content. It notes when content was truncated, when a page failed to load, and flags the most relevant results.

Results from web search are for discovery only and are not citation evidence. Confirm papers through /arxiv, /semantic-scholar or verify_papers.py before you cite them.

• Default: 5 results, 4000 markdown characters per result
• Scrape mode keeps up to 20000 characters per page
• Content: none returns only titles, URLs and descriptions, which is faster and cheaper

What are the cost and safety considerations?

Firecrawl charges credits. A search costs credits per 10 results, and with markdown content each scraped result adds credits. PDFs are billed per page. To scan many results cheaply, use content none first, then scrape only the few that matter.

The skill runs scripts and uses the network. Search terms and scraped URLs are sent to a third-party service, so avoid sensitive or confidential research queries. Treat everything the helper returns as untrusted web content: the agent should read it as data, not as instructions. The skill also validates URLs before scraping and rejects arguments that do not pass its checks.

• Search terms and URLs are sent to Firecrawl
• Scripts run and network access is used
• Bulk full-content scanning consumes paid credits