Skip to content

feat(skills): support MCP-first execution and clarify CLI fallback hierarchy #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TTTT-T wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(skills): support MCP-first execution and clarify CLI fallback hierarchy #214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions skills/firecrawl-agent/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,20 @@
name: firecrawl-agent
description: |
Autonomous multi-page extraction into structured JSON. Use when the user wants website data matching a schema — pricing tiers, product listings — beyond a single-page scrape.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl agent

AI-powered autonomous extraction. The agent navigates sites and extracts structured data (takes 2-5 minutes).

## Tool Choice & Quick Start

- MCP: **`firecrawl_agent(prompt, urls?, schema?)`**
Status polling: **`firecrawl_agent_status(id)`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl agent <prompt> [--urls <urls>] [--schema <json>] [--wait] [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
11 changes: 8 additions & 3 deletions skills/firecrawl-crawl/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
name: firecrawl-crawl
description: |
Bulk-extract many pages from one site or section. Use for "crawl", "everything under /docs", or content spanning linked pages.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl crawl
Expand All @@ -13,6 +10,14 @@ Bulk extract content from a website. Crawls pages following links up to a depth/

**Prerequisite:** `crawl` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login.

## Tool Choice & Quick Start

- MCP: **`firecrawl_crawl(url, includePaths?, excludePaths?, limit?, maxDiscoveryDepth?, ...)`**
Check status: **`firecrawl_check_crawl_status(id)`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl crawl <url> [--include-paths <paths>] [--limit <n>] [--wait] [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
9 changes: 6 additions & 3 deletions skills/firecrawl-download/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
name: firecrawl-download
description: |
Save a site or section as local files (markdown, screenshots). Use for "download the site", offline docs, or a local copy for reference.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl download (invoked as `firecrawl x download`)
Expand All @@ -13,6 +10,12 @@ allowed-tools:

**Prerequisite:** `download` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login.

## Tool Choice & Quick Start

- MCP: Use **`firecrawl_map(url, ...)`** to discover pages and **`firecrawl_scrape(url, ...)`** to extract and save page contents.

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The MCP-first instruction loses the download skill's core behavior. It tells the agent only to 'extract and save page contents' with firecrawl_scrape, but that tool returns content into the conversation and does not write local files or screenshots unless the agent explicitly requests formats: ["markdown", "screenshot"] and writes them itself. A user asking to 'download the site' (with screenshots, per the CLI --screenshot) in an MCP-first environment gets in-chat content rather than the local .firecrawl/ file tree the CLI produces. Ask the agent to request the screenshot/markdown formats and save each page to .firecrawl/, so the two paths stay equivalent.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-download/SKILL.md, line 15:

<comment>The MCP-first instruction loses the download skill's core behavior. It tells the agent only to 'extract and save page contents' with `firecrawl_scrape`, but that tool returns content into the conversation and does not write local files or screenshots unless the agent explicitly requests `formats: ["markdown", "screenshot"]` and writes them itself. A user asking to 'download the site' (with screenshots, per the CLI `--screenshot`) in an MCP-first environment gets in-chat content rather than the local `.firecrawl/` file tree the CLI produces. Ask the agent to request the screenshot/markdown formats and save each page to `.firecrawl/`, so the two paths stay equivalent.</comment>

<file context>
@@ -13,6 +10,12 @@ allowed-tools:
 
+## Tool Choice & Quick Start
+
+- MCP: Use **`firecrawl_map(url, ...)`** to discover pages and **`firecrawl_scrape(url, ...)`** to extract and save page contents.
+- CLI: **`firecrawl x download <url> [--include-paths <paths>] [--limit <n>] -y`**
+  Command line batch download directly to `.firecrawl/`.
</file context>
Suggested change
- MCP: Use **`firecrawl_map(url, ...)`** to discover pages and **`firecrawl_scrape(url, ...)`** to extract and save page contents.
- MCP: Use **`firecrawl_map(url, ...)`** to discover pages, then **`firecrawl_scrape(url, formats: ["markdown", "screenshot"], ...)`** on each page and save the results to local files under `.firecrawl/`.
Fix with cubic

- CLI: **`firecrawl x download <url> [--include-paths <paths>] [--limit <n>] -y`**
Command line batch download directly to `.firecrawl/`.

Maps the site origin first to discover pages, then scrapes each one into nested directories under `.firecrawl/`. Use `--include-paths` to scope a non-root URL to one section. Automated runs always pass `-y` — without it the command opens an interactive wizard that blocks on a prompt.

## Quick start
Expand Down
11 changes: 8 additions & 3 deletions skills/firecrawl-interact/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,20 @@
name: firecrawl-interact
description: |
Drive a live browser on a scraped page: click, fill forms, log in, paginate, infinite-scroll. Use when content requires interaction or a scrape failed or returned incomplete content.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl interact

Interact with scraped pages in a live browser session. Scrape a page first, then use natural language prompts or code to click, fill forms, navigate, and extract data. For web searches, use `search` — interact is for acting on a specific page.

## Tool Choice & Quick Start

- MCP: **`firecrawl_interact(url?, scrapeId?, prompt?, code?, ...)`**
Stop session: **`firecrawl_interact_stop(scrapeId)`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl interact [scrapeId] <prompt> [--code <code>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
10 changes: 7 additions & 3 deletions skills/firecrawl-map/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
name: firecrawl-map
description: |
Discover and list a site's URLs, with search filtering. Use for "map the site" or "find the URL for" requests — when the user knows the site but not the exact page, or wants site structure.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl map
Expand All @@ -13,6 +10,13 @@ Discover URLs on a site. Use `--search` to find a specific page within a large s

**Prerequisite:** `map` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login.

## Tool Choice & Quick Start

- MCP: **`firecrawl_map(url, search?, limit?, ...)`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl map <url> [--search <query>] [--limit <n>] [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
11 changes: 8 additions & 3 deletions skills/firecrawl-monitor/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,20 @@
name: firecrawl-monitor
description: |
Alert by webhook/email on web changes — use for "monitor/watch/track/alert me when": recurring checks on known URLs (prefer over repeated one-off scrapes) or web-wide watches for new results (queries + goal).
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl monitor

Detect when content on a website changes and get notified by webhook or email. Firecrawl handles fetching, diffing, judging, and notifying server-side. Each page in a check is labeled `same`, `new`, `changed`, `removed`, or `error`.

## Tool Choice & Quick Start

- MCP: **`firecrawl_monitor_create(goal?, page?, pages?, queries?, scheduleText?, ...)`**
Manage & check: **`firecrawl_monitor_get`**, **`firecrawl_monitor_run`**, **`firecrawl_monitor_check`**, **`firecrawl_monitor_checks`**, **`firecrawl_monitor_update`**, **`firecrawl_monitor_delete`**, **`firecrawl_monitor_list`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl monitor <create|list|get|update|delete|run|checks|check>`**
Fallback when running in a CLI environment.

**Pick a target mode** by what you're watching:

| Mode | Flags | Watches |
Expand Down
10 changes: 7 additions & 3 deletions skills/firecrawl-parse/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,19 @@
name: firecrawl-parse
description: |
Convert a local file (PDF, DOCX, XLSX, HTML, …) to markdown, or answer questions about its content. Use whenever the input is a file path, not a URL.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl parse

Turn a local document into clean markdown on disk. Supports **PDF, DOCX, DOC, ODT, RTF, XLSX, XLS, HTML/HTM**.

## Tool Choice & Quick Start

- MCP: **`firecrawl_parse(filePath?, formats?, ...)`**
Call directly when Firecrawl MCP tools are exposed.

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When the exposed MCP server is hosted remotely, it cannot read a local filePath directly. Document the upload-handoff and uploadRef flow, or limit this shortcut to local/self-hosted MCP connections.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-parse/SKILL.md, line 14:

<comment>When the exposed MCP server is hosted remotely, it cannot read a local `filePath` directly. Document the upload-handoff and `uploadRef` flow, or limit this shortcut to local/self-hosted MCP connections.</comment>

<file context>
@@ -2,15 +2,19 @@
+## Tool Choice & Quick Start
+
+- MCP: **`firecrawl_parse(filePath?, formats?, ...)`**
+  Call directly when Firecrawl MCP tools are exposed.
+- CLI: **`firecrawl parse <file> [-o <path>]`**
+  Fallback when running in a CLI environment.
</file context>
Fix with cubic

- CLI: **`firecrawl parse <file> [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

Always save to `.firecrawl/` with `-o` — parsed docs can be hundreds of KB and blow up context if streamed to stdout. Add `.firecrawl/` to `.gitignore`.
Expand Down
10 changes: 7 additions & 3 deletions skills/firecrawl-scrape/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,19 @@
name: firecrawl-scrape
description: |
Extract a URL's content as clean markdown, including JS-rendered pages. Use whenever the user provides a URL and wants its content; prefer over WebFetch.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl scrape

Scrape one or more URLs. Returns clean, LLM-optimized markdown. Multiple URLs are scraped concurrently.

## Tool Choice & Quick Start

- MCP: **`firecrawl_scrape(url, formats?, onlyMainContent?, waitFor?, ...)`**
Call directly when Firecrawl MCP tools are exposed.
- CLI: **`firecrawl scrape <url> [--only-main-content] [--wait-for <ms>] [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
11 changes: 8 additions & 3 deletions skills/firecrawl-search/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,20 @@
name: firecrawl-search
description: |
Web search with full page content. Use when no URL is known: finding sources, articles, or news. For papers use firecrawl-research-index; for library, API, error, or bug questions use firecrawl-developer-index.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# firecrawl search

Web search with optional content scraping. Returns search results as JSON, optionally with full page content.

## Tool Choice & Quick Start

- MCP: **`firecrawl_search(query, scrapeOptions?, categories?, limit?, sources?, ...)`**
Call directly when Firecrawl MCP tools are exposed.
Feedback: **`firecrawl_search_feedback(searchId, rating, ...)`**

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: In an MCP-only environment, the required feedback step still invokes firecrawl search-feedback in the background. Add an MCP branch that calls firecrawl_search_feedback and retain the CLI command only for CLI searches.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-search/SKILL.md, line 15:

<comment>In an MCP-only environment, the required feedback step still invokes `firecrawl search-feedback` in the background. Add an MCP branch that calls `firecrawl_search_feedback` and retain the CLI command only for CLI searches.</comment>

<file context>
@@ -2,15 +2,20 @@
+
+- MCP: **`firecrawl_search(query, scrapeOptions?, categories?, limit?, sources?, ...)`**
+  Call directly when Firecrawl MCP tools are exposed.
+  Feedback: **`firecrawl_search_feedback(searchId, rating, ...)`**
+- CLI: **`firecrawl search <query> [--scrape] [--json] [-o <path>]`**
+  Fallback when running in a CLI environment.
</file context>
Fix with cubic

- CLI: **`firecrawl search <query> [--scrape] [--json] [-o <path>]`**
Fallback when running in a CLI environment.

## Quick start

```bash
Expand Down
39 changes: 23 additions & 16 deletions skills/firecrawl/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,20 @@
name: firecrawl
description: |
Any live-web task via the Firecrawl CLI — including ordinary web research: searching the web, reading or extracting pages, gathering sources, discovering site URLs, bulk extraction, downloading a site, change alerts, or pages needing clicks/login — web only; local files route to firecrawl-parse. For papers use firecrawl-research-index; for library, API, error, or bug questions use firecrawl-developer-index.
allowed-tools:
- Bash(firecrawl *)
- Bash(npx firecrawl-cli *)
---

# Firecrawl CLI

## Tool Selection Hierarchy

Follow this precedence order based on your current execution environment:

1. **MCP First (Recommended)**: If Firecrawl MCP tools (`firecrawl_search`, `firecrawl_scrape`, `firecrawl_map`, `firecrawl_crawl`, `firecrawl_agent`, `firecrawl_interact`, `firecrawl_parse`, `firecrawl_monitor_*`, `firecrawl_developer_search`, `firecrawl_research_*`) are available in the tool catalog, **call the MCP tools directly**.

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When the CLI is absent, MCP-first execution bypasses this skill's required .firecrawl/ persistence and saved-source citation flow. Document how to save and bounded-read MCP results with host filesystem tools, or make those requirements conditional for MCP execution.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 13:

<comment>When the CLI is absent, MCP-first execution bypasses this skill's required `.firecrawl/` persistence and saved-source citation flow. Document how to save and bounded-read MCP results with host filesystem tools, or make those requirements conditional for MCP execution.</comment>

<file context>
@@ -2,13 +2,20 @@
+
+Follow this precedence order based on your current execution environment:
+
+1. **MCP First (Recommended)**: If Firecrawl MCP tools (`firecrawl_search`, `firecrawl_scrape`, `firecrawl_map`, `firecrawl_crawl`, `firecrawl_agent`, `firecrawl_interact`, `firecrawl_parse`, `firecrawl_monitor_*`, `firecrawl_developer_search`, `firecrawl_research_*`) are available in the tool catalog, **call the MCP tools directly**.
+2. **CLI Fallback**: If MCP tools are not exposed, check if the `firecrawl` CLI is installed on `PATH` and run CLI commands.
+3. **Missing Local CLI != Unavailable**: If `firecrawl` command is not found on `PATH`, do **not** declare Firecrawl unavailable without checking for exposed MCP tools first. **Do not run unauthorized `npx` commands or install packages silently**.
</file context>
Fix with cubic

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: On MCP-only hosts, this new route leaves the required search-feedback step pointing at the missing firecrawl CLI. Add an MCP branch using firecrawl_search_feedback and keep the CLI command for CLI searches.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 13:

<comment>On MCP-only hosts, this new route leaves the required search-feedback step pointing at the missing `firecrawl` CLI. Add an MCP branch using `firecrawl_search_feedback` and keep the CLI command for CLI searches.</comment>

<file context>
@@ -2,13 +2,20 @@
+
+Follow this precedence order based on your current execution environment:
+
+1. **MCP First (Recommended)**: If Firecrawl MCP tools (`firecrawl_search`, `firecrawl_scrape`, `firecrawl_map`, `firecrawl_crawl`, `firecrawl_agent`, `firecrawl_interact`, `firecrawl_parse`, `firecrawl_monitor_*`, `firecrawl_developer_search`, `firecrawl_research_*`) are available in the tool catalog, **call the MCP tools directly**.
+2. **CLI Fallback**: If MCP tools are not exposed, check if the `firecrawl` CLI is installed on `PATH` and run CLI commands.
+3. **Missing Local CLI != Unavailable**: If `firecrawl` command is not found on `PATH`, do **not** declare Firecrawl unavailable without checking for exposed MCP tools first. **Do not run unauthorized `npx` commands or install packages silently**.
</file context>
Fix with cubic

2. **CLI Fallback**: If MCP tools are not exposed, check if the `firecrawl` CLI is installed on `PATH` and run CLI commands.
3. **Missing Local CLI != Unavailable**: If `firecrawl` command is not found on `PATH`, do **not** declare Firecrawl unavailable without checking for exposed MCP tools first. **Do not run unauthorized `npx` commands or install packages silently**.

---

Search, scrape, and interact with the web. Returns clean markdown optimized for LLM context windows.

Run `firecrawl --help` or `firecrawl <command> --help` for full option details. For app integration or outcome workflows (research briefs, SEO audits, etc.), route to the `firecrawl-build` / `firecrawl-workflows` skills — see [When to Load References](#when-to-load-references).
Expand All @@ -30,19 +37,19 @@ Follow this escalation pattern:
5. **Monitor** - Need recurring checks or ongoing alerts. Prefer setting a monitor with `--page` plus `--goal` instead of doing repeated one-off scrapes.
6. **Interact** - Scrape first, then interact with the page (pagination, modals, form submissions, multi-step navigation).

| Need | Command | When |
| --------------------------- | --------------------- | --------------------------------------------------------------- |
| Find pages on a topic | `search` | No specific URL yet |
| Find research papers | `research` | Biomedical/clinical/scientific literature — use the paper index |
| Answer a coding question | `developer` | Issues, merged PRs, READMEs, and docs — not a general web page |
| Get a page's content | `scrape` | Have a URL, page is static or JS-rendered |
| Find URLs within a site | `map` | Need to locate a specific subpage |
| Bulk extract a site section | `crawl` | Need many pages (e.g., all /docs/) |
| AI-powered data extraction | `agent` | Need structured data from complex sites |
| Interact with a page | `scrape` + `interact` | Content requires clicks, form fills, pagination, or login |
| Download a site to files | `x download` | Save an entire site as local files |
| Parse a local file | `parse` | File on disk (PDF, DOCX, XLSX, etc.) — not a URL |
| Watch pages for changes | `monitor` | Schedule recurring scrapes/crawls, diff against snapshots |
| Need | MCP Tool | CLI Command | When |
| --------------------------- | ------------------------------------ | --------------------- | --------------------------------------------------------------- |
| Find pages on a topic | `firecrawl_search` | `search` | No specific URL yet |
| Find research papers | `firecrawl_research_search_papers` | `research` | Biomedical/clinical/scientific literature — use the paper index |

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When CLI fallback handles a paper search, this row directs the agent to run research, which does not perform a search. Use research search-papers in the CLI column.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 43:

<comment>When CLI fallback handles a paper search, this row directs the agent to run `research`, which does not perform a search. Use `research search-papers` in the CLI column.</comment>

<file context>
@@ -30,19 +37,19 @@ Follow this escalation pattern:
+| Need                        | MCP Tool                             | CLI Command           | When                                                            |
+| --------------------------- | ------------------------------------ | --------------------- | --------------------------------------------------------------- |
+| Find pages on a topic       | `firecrawl_search`                   | `search`              | No specific URL yet                                             |
+| Find research papers        | `firecrawl_research_search_papers`   | `research`            | Biomedical/clinical/scientific literature — use the paper index |
+| Answer a coding question    | `firecrawl_developer_search`         | `developer`           | Issues, merged PRs, READMEs, and docs — not a general web page  |
+| Get a page's content        | `firecrawl_scrape`                   | `scrape`              | Have a URL, page is static or JS-rendered                       |
</file context>
Suggested change
| Find research papers | `firecrawl_research_search_papers` | `research` | Biomedical/clinical/scientific literature — use the paper index |
| Find research papers | `firecrawl_research_search_papers` | `research search-papers` | Biomedical/clinical/scientific literature — use the paper index |
Fix with cubic

| Answer a coding question | `firecrawl_developer_search` | `developer` | Issues, merged PRs, READMEs, and docs — not a general web page |
| Get a page's content | `firecrawl_scrape` | `scrape` | Have a URL, page is static or JS-rendered |
| Find URLs within a site | `firecrawl_map` | `map` | Need to locate a specific subpage |
| Bulk extract a site section | `firecrawl_crawl` | `crawl` | Need many pages (e.g., all /docs/) |
| AI-powered data extraction | `firecrawl_agent` | `agent` | Need structured data from complex sites |
| Interact with a page | `firecrawl_interact` | `scrape` + `interact` | Content requires clicks, form fills, pagination, or login |
| Download a site to files | `firecrawl_map` + `firecrawl_scrape` | `x download` | Save an entire site as local files |
| Parse a local file | `firecrawl_parse` | `parse` | File on disk (PDF, DOCX, XLSX, etc.) — not a URL |
| Watch pages for changes | `firecrawl_monitor_create` | `monitor` | Schedule recurring scrapes/crawls, diff against snapshots |

For detailed command reference, run `firecrawl <command> --help`.

Expand Down
14 changes: 10 additions & 4 deletions skills/firecrawl/rules/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ description: |

# Firecrawl CLI Installation

## Important: Tool Availability & Execution Hierarchy

1. **Check for Native MCP Tools First**: Before attempting to install or check the CLI, verify whether Firecrawl MCP tools (e.g. `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl`, `firecrawl_map`, etc.) are exposed in your current agent environment. If MCP tools are available, **use them directly** without installing the CLI.
2. **Missing Local CLI != Firecrawl Unavailable**: If `firecrawl` command is not found on `PATH`, this only means the CLI executable is absent locally; it does not mean Firecrawl functionality is unavailable. Check for MCP tools before reporting failure.
3. **No Unauthorized Package Installation**: Agents must **not** execute `npx firecrawl-cli init` or install npm packages unless explicitly requested by the user.

@cubic-dev-ai cubic-dev-ai Bot Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Rule 3 forbids running npx firecrawl-cli init unless the user explicitly requests it, but the 'Quick Setup (Recommended)' block directly below recommends npx -y firecrawl-cli@latest init -y --browser and calls it 'safe to re-run when the CLI is missing' — no user-request condition. A coding agent reading both gets contradictory guidance on when installing is allowed and which command to run ('Command not found' step 3 instead says npm install -g firecrawl-cli@latest). Qualify the Quick Setup to require explicit user consent (or reword rule 3) and use a single install command so the docs are internally consistent.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/rules/install.md, line 16:

<comment>Rule 3 forbids running `npx firecrawl-cli init` unless the user explicitly requests it, but the 'Quick Setup (Recommended)' block directly below recommends `npx -y firecrawl-cli@latest init -y --browser` and calls it 'safe to re-run when the CLI is missing' — no user-request condition. A coding agent reading both gets contradictory guidance on when installing is allowed and which command to run ('Command not found' step 3 instead says `npm install -g firecrawl-cli@latest`). Qualify the Quick Setup to require explicit user consent (or reword rule 3) and use a single install command so the docs are internally consistent.</comment>

<file context>
@@ -9,6 +9,12 @@ description: |
+
+1. **Check for Native MCP Tools First**: Before attempting to install or check the CLI, verify whether Firecrawl MCP tools (e.g. `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl`, `firecrawl_map`, etc.) are exposed in your current agent environment. If MCP tools are available, **use them directly** without installing the CLI.
+2. **Missing Local CLI != Firecrawl Unavailable**: If `firecrawl` command is not found on `PATH`, this only means the CLI executable is absent locally; it does not mean Firecrawl functionality is unavailable. Check for MCP tools before reporting failure.
+3. **No Unauthorized Package Installation**: Agents must **not** execute `npx firecrawl-cli init` or install npm packages unless explicitly requested by the user.
+
 ## Quick Setup (Recommended)
</file context>
Fix with cubic


## Quick Setup (Recommended)

```bash
Expand Down Expand Up @@ -84,8 +90,8 @@ If you cannot obtain a key and the user cannot sign up, search, scrape, and inte

### Command not found

If `firecrawl` is not found after installation:
If `firecrawl` is not found:

1. Ensure npm global bin is in PATH
2. Try: `npx firecrawl-cli@latest --version`
3. Reinstall: `npm install -g firecrawl-cli@latest`
1. Check if Firecrawl MCP tools are exposed in the agent environment — if so, use them directly instead of troubleshooting CLI.
2. If CLI is explicitly needed, ensure npm global bin directory is included in `PATH`.
3. If CLI installation was requested by the user, install via `npm install -g firecrawl-cli@latest`.