From acee3e46c201da7f1cabf7600effb16cbc8d9a03 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 17:18:40 -0400 Subject: [PATCH 01/16] remove hard coded version --- skills/firecrawl-cli/SKILL.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index d6ef72e504..4f022f4091 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -20,7 +20,7 @@ If the task is to integrate Firecrawl into an application, add `FIRECRAWL_API_KE Must be installed. Check with `firecrawl --status`. ``` - πŸ”₯ firecrawl cli v1.8.0 + πŸ”₯ firecrawl cli ● Authenticated via FIRECRAWL_API_KEY Concurrency: 0/100 jobs (parallel scrape limit) @@ -194,9 +194,7 @@ The `check` response then carries a per-field diff (paths like `plans[0].price`) }, "snapshot": { "json": { - "plans": [ - /* current full extraction */ - ] + "plans": [/* current full extraction */] } } } From 4303e02ce529cb0bf38fe741a4231320fa08f9ee Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 17:21:10 -0400 Subject: [PATCH 02/16] docs(skills): fix allowed-tools npx pattern and broken workflow links --- skills/firecrawl-agent/SKILL.md | 2 +- skills/firecrawl-cli/SKILL.md | 2 +- skills/firecrawl-crawl/SKILL.md | 4 ++-- skills/firecrawl-download/SKILL.md | 2 +- skills/firecrawl-interact/SKILL.md | 4 ++-- skills/firecrawl-map/SKILL.md | 4 ++-- skills/firecrawl-monitor/SKILL.md | 4 ++-- skills/firecrawl-parse/SKILL.md | 2 +- skills/firecrawl-scrape/SKILL.md | 4 ++-- skills/firecrawl-search/SKILL.md | 4 ++-- 10 files changed, 16 insertions(+), 16 deletions(-) diff --git a/skills/firecrawl-agent/SKILL.md b/skills/firecrawl-agent/SKILL.md index 18fd81bff5..4c32a3b6e2 100644 --- a/skills/firecrawl-agent/SKILL.md +++ b/skills/firecrawl-agent/SKILL.md @@ -4,7 +4,7 @@ description: | AI-powered autonomous data extraction that navigates complex sites and returns structured JSON. Use this skill when the user wants structured data from websites, needs to extract pricing tiers, product listings, directory entries, or any data as JSON with a schema. Triggers on "extract structured data", "get all the products", "pull pricing info", "extract as JSON", or when the user provides a JSON schema for website data. More powerful than simple scraping for multi-page structured extraction. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl agent diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index 4f022f4091..9580745877 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -4,7 +4,7 @@ description: | Search, scrape, and interact with the web via the Firecrawl CLI. Use this skill whenever the user wants to search the web, find articles, research a topic, look something up online, scrape a webpage, grab content from a URL, get data from a website, crawl documentation, download a site, or interact with pages that need clicks or logins. Also use when they say "fetch this page", "pull the content from", "get the page at https://", or reference external websites. This provides real-time web search with full page content and interact capabilities β€” beyond what Claude can do natively with built-in tools. Do NOT trigger for local file operations, git commands, deployments, or code editing tasks. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # Firecrawl CLI diff --git a/skills/firecrawl-crawl/SKILL.md b/skills/firecrawl-crawl/SKILL.md index ca6e6b5aaf..db001e57bd 100644 --- a/skills/firecrawl-crawl/SKILL.md +++ b/skills/firecrawl-crawl/SKILL.md @@ -4,7 +4,7 @@ description: | Bulk extract content from an entire website or site section. Use this skill when the user wants to crawl a site, extract all pages from a docs section, bulk-scrape multiple pages following links, or says "crawl", "get all the pages", "extract everything under /docs", "bulk extract", or needs content from many pages on the same site. Handles depth limits, path filtering, and concurrent extraction. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl crawl @@ -15,7 +15,7 @@ Bulk extract content from a website. Crawls pages following links up to a depth/ - You need content from many pages on a site (e.g., all `/docs/`) - You want to extract an entire site section -- Step 4 in the [workflow escalation pattern](firecrawl-cli): search β†’ scrape β†’ map β†’ **crawl** β†’ interact +- Step 4 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ **crawl** β†’ interact ## Quick start diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index d2beeb7c66..823a27307b 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -4,7 +4,7 @@ description: | Download an entire website as local files β€” markdown, screenshots, or multiple formats per page. Use this skill when the user wants to save a site locally, download documentation for offline use, bulk-save pages as files, or says "download the site", "save as local files", "offline copy", "download all the docs", or "save for reference". Combines site mapping and scraping into organized local directories. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl download diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index 7468dd2083..25844b9002 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -4,7 +4,7 @@ description: | Control and interact with a live browser session on any scraped page β€” click buttons, fill forms, navigate flows, and extract data using natural language prompts or code. Use when the user needs to interact with a webpage beyond simple scraping: logging into a site, submitting forms, clicking through pagination, handling infinite scroll, navigating multi-step checkout or wizard flows, or when a regular scrape failed because content is behind JavaScript interaction. Also useful for authenticated scraping via profiles. Triggers on "interact", "click", "fill out the form", "log in to", "sign in", "submit", "paginated", "next page", "infinite scroll", "interact with the page", "navigate to", "open a session", or "scrape failed". allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl interact @@ -16,7 +16,7 @@ Interact with scraped pages in a live browser session. Scrape a page first, then - Content requires interaction: clicks, form fills, pagination, login - `scrape` failed because content is behind JavaScript interaction - You need to navigate a multi-step flow -- Last resort in the [workflow escalation pattern](firecrawl-cli): search β†’ scrape β†’ map β†’ crawl β†’ **interact** +- Last resort in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ **interact** - **Never use interact for web searches** β€” use `search` instead ## Quick start diff --git a/skills/firecrawl-map/SKILL.md b/skills/firecrawl-map/SKILL.md index 77eaacf591..aa949c56fe 100644 --- a/skills/firecrawl-map/SKILL.md +++ b/skills/firecrawl-map/SKILL.md @@ -4,7 +4,7 @@ description: | Discover and list all URLs on a website, with optional search filtering. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where something is on a domain, or says "map the site", "find the URL for", "what pages are on", or "list all pages". Essential when the user knows which site but not which exact page. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl map @@ -15,7 +15,7 @@ Discover URLs on a site. Use `--search` to find a specific page within a large s - You need to find a specific subpage on a large site - You want a list of all URLs on a site before scraping or crawling -- Step 3 in the [workflow escalation pattern](firecrawl-cli): search β†’ scrape β†’ **map** β†’ crawl β†’ interact +- Step 3 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ **map** β†’ crawl β†’ interact ## Quick start diff --git a/skills/firecrawl-monitor/SKILL.md b/skills/firecrawl-monitor/SKILL.md index dc23d1d551..79f28a95b9 100644 --- a/skills/firecrawl-monitor/SKILL.md +++ b/skills/firecrawl-monitor/SKILL.md @@ -4,7 +4,7 @@ description: | Detect when content on a website changes and get notified by webhook or email β€” no cron jobs, scrapers, or diff scripts required. Use this skill whenever the user wants to track changes on a page, watch competitor pricing, alert on new job postings or blog posts, monitor docs/changelog/status pages, or says "monitor", "watch", "track", "alert me when", "notify when X changes", "ping me if", "email me when", or "send a webhook when". It also covers **web monitors** β€” when the user wants to monitor the *web itself* for new results rather than watch a known URL: track new product launches, funding rounds, papers, news, releases, or mentions across the web, or says "monitor the web for", "watch for new X", or "alert me when something new appears about ...". For those, give search queries plus a goal instead of a URL. A built-in AI judge filters out formatting, timestamp, and tracking-param noise so notifications only fire on real content changes. Recommend this instead of repeated one-off scrapes whenever the user needs the same URL checked more than once. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl monitor @@ -31,7 +31,7 @@ The first three watch URLs you already have. **Web search** is the odd one out - **Monitoring the web** for _new_ results rather than changes to a known page β€” new launches, funding rounds, papers, news, releases, or brand mentions surfaced by search across the whole web (a **web monitor**: `--queries` + `--goal`) - "Alert me when...", "notify me when...", "email me if...", "send a webhook when...", "ping me if X changes", "track this page", "monitor the web for...", "watch for new..." - Anywhere the user would otherwise wire up cron + a scraper + a diff library + SMTP themselves -- Step 5 in the [workflow escalation pattern](firecrawl-cli): search β†’ scrape β†’ map β†’ crawl β†’ **monitor** β†’ interact +- Step 5 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ **monitor** β†’ interact **Bias toward `monitor`** whenever the request implies notifications or recurrence. A single page read once = `scrape`. A single page where the user wants to be told when it changes = `monitor --page --goal "..." --email|--webhook-url ...`. diff --git a/skills/firecrawl-parse/SKILL.md b/skills/firecrawl-parse/SKILL.md index f350cb2a98..eeec7c2c06 100644 --- a/skills/firecrawl-parse/SKILL.md +++ b/skills/firecrawl-parse/SKILL.md @@ -4,7 +4,7 @@ description: | Efficiently extract and convert the contents of any local fileβ€”such as PDF, DOCX, DOC, ODT, RTF, XLSX, XLS, or HTMLβ€”into clean, well-formatted markdown saved to disk. Use this skill whenever the user requests to parse, read, or extract information from a file on their computer, including phrases like β€œparse this PDF”, β€œconvert this document”, β€œread this file”, β€œextract text from”, or when a local file path (not a URL) is provided. This skill offers advanced options like generating AI-powered summaries and answering questions based on the file's content. Prefer this tool over `scrape` when handling local files to deliver precise, structured outputs for downstream tasks. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl parse diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index 6c6612756c..b40101c643 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -4,7 +4,7 @@ description: | Extract clean markdown from any URL, including JavaScript-rendered SPAs. Use this skill whenever the user provides a URL and wants its content, says "scrape", "grab", "fetch", "pull", "get the page", "extract from this URL", or "read this webpage". Handles JS-rendered pages, multiple concurrent URLs, and returns LLM-optimized markdown. Use this instead of WebFetch for any webpage content extraction. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl scrape @@ -15,7 +15,7 @@ Scrape one or more URLs. Returns clean, LLM-optimized markdown. Multiple URLs ar - You have a specific URL and want its content - The page is static or JS-rendered (SPA) -- Step 2 in the [workflow escalation pattern](firecrawl-cli): search β†’ **scrape** β†’ map β†’ crawl β†’ interact +- Step 2 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ **scrape** β†’ map β†’ crawl β†’ interact ## Quick start diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 00c110ed24..eedb318214 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -4,7 +4,7 @@ description: | Web search with full page content extraction, plus routing to Firecrawl's research paper index. Use this skill whenever the user asks to search the web, find articles, research a topic, look something up, find recent news, discover sources, or says "search for", "find me", "look up", "what are people saying about", or "find articles about". Also use it for scientific literature β€” finding papers, studies, trials, or preprints on PubMed, bioRxiv, medRxiv, or arXiv. Returns real search results with optional full-page markdown β€” not just snippets. Provides capabilities beyond Claude's built-in WebSearch. allowed-tools: - Bash(firecrawl *) - - Bash(npx firecrawl *) + - Bash(npx firecrawl-cli *) --- # firecrawl search @@ -16,7 +16,7 @@ Web search with optional content scraping. Returns search results as JSON, optio - You don't have a specific URL yet - You need to find pages, answer questions, or discover sources - You need research papers β€” see [Paper search](#paper-search), which routes to `firecrawl research`, not to `search --categories research` -- First step in the [workflow escalation pattern](firecrawl-cli): search β†’ scrape β†’ map β†’ crawl β†’ interact +- First step in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ interact ## Quick start From 8f2c5f38fcd2c65ee9014cf75cb2814608769961 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 16:14:08 -0400 Subject: [PATCH 03/16] docs(skills): fix broken command examples --- skills/firecrawl-agent/SKILL.md | 27 ++++++++++++++------------- skills/firecrawl-cli/SKILL.md | 2 +- skills/firecrawl-download/SKILL.md | 14 +++++++------- skills/firecrawl-interact/SKILL.md | 8 +++++--- skills/firecrawl-scrape/SKILL.md | 2 +- 5 files changed, 28 insertions(+), 25 deletions(-) diff --git a/skills/firecrawl-agent/SKILL.md b/skills/firecrawl-agent/SKILL.md index 4c32a3b6e2..a36462cf2e 100644 --- a/skills/firecrawl-agent/SKILL.md +++ b/skills/firecrawl-agent/SKILL.md @@ -21,27 +21,28 @@ AI-powered autonomous extraction. The agent navigates sites and extracts structu ```bash # Extract structured data -firecrawl agent "extract all pricing tiers" --wait -o .firecrawl/pricing.json +firecrawl agent "extract all pricing tiers" --wait --json -o .firecrawl/pricing.json # With a JSON schema for structured output -firecrawl agent "extract products" --schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' --wait -o .firecrawl/products.json +firecrawl agent "extract products" --schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' --wait --json -o .firecrawl/products.json # Focus on specific pages -firecrawl agent "get feature list" --urls "" --wait -o .firecrawl/features.json +firecrawl agent "get feature list" --urls "" --wait --json -o .firecrawl/features.json ``` ## Options -| Option | Description | -| ---------------------- | ----------------------------------------- | -| `--urls ` | Starting URLs for the agent | -| `--model ` | Model to use: spark-1-mini or spark-1-pro | -| `--schema ` | JSON schema for structured output | -| `--schema-file ` | Path to JSON schema file | -| `--max-credits ` | Credit limit for this agent run | -| `--wait` | Wait for agent to complete | -| `--pretty` | Pretty print JSON output | -| `-o, --output ` | Output file path | +| Option | Description | +| ---------------------- | ----------------------------------------------------- | +| `--urls ` | Starting URLs for the agent | +| `--model ` | Model to use: spark-1-mini or spark-1-pro | +| `--schema ` | JSON schema for structured output | +| `--schema-file ` | Path to JSON schema file | +| `--max-credits ` | Credit limit for this agent run | +| `--wait` | Wait for agent to complete | +| `--json` | Output as JSON | +| `--pretty` | Pretty print JSON (`--wait` results require `--json`) | +| `-o, --output ` | Output file path | ## Tips diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index 9580745877..75c1b09ef6 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -65,7 +65,7 @@ Follow this escalation pattern: | 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 | `download` | Save an entire site as local files | +| 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 | diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index 823a27307b..07cd43cdf3 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -9,7 +9,7 @@ allowed-tools: # firecrawl download -> **Experimental.** Convenience command that combines `map` + `scrape` to save an entire site as local files. +> **Experimental.** `download` is available under the `firecrawl x` command group. Maps the site first to discover pages, then scrapes each one into nested directories under `.firecrawl/`. All scrape options work with download. Always pass `-y` to skip the confirmation prompt. @@ -23,23 +23,23 @@ Maps the site first to discover pages, then scrapes each one into nested directo ```bash # Interactive wizard (picks format, screenshots, paths for you) -firecrawl download https://docs.example.com +firecrawl x download https://docs.example.com # With screenshots -firecrawl download https://docs.example.com --screenshot --limit 20 -y +firecrawl x download https://docs.example.com --screenshot --limit 20 -y # Multiple formats (each saved as its own file per page) -firecrawl download https://docs.example.com --format markdown,links --screenshot --limit 20 -y +firecrawl x download https://docs.example.com --format markdown,links --screenshot --limit 20 -y # Creates per page: index.md + links.txt + screenshot.png # Filter to specific sections -firecrawl download https://docs.example.com --include-paths "/features,/sdks" +firecrawl x download https://docs.example.com --include-paths "/features,/sdks" # Skip translations -firecrawl download https://docs.example.com --exclude-paths "/zh,/ja,/fr,/es,/pt-BR" +firecrawl x download https://docs.example.com --exclude-paths "/zh,/ja,/fr,/es,/pt-BR" # Full combo -firecrawl download https://docs.example.com \ +firecrawl x download https://docs.example.com \ --include-paths "/features,/sdks" \ --exclude-paths "/zh,/ja" \ --only-main-content \ diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index 25844b9002..ed66dd6da1 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -31,8 +31,8 @@ firecrawl interact --prompt "Fill in the email field with test@example.com" firecrawl interact --prompt "Extract the pricing table" # 3. Or use code for precise control -firecrawl interact --code "agent-browser click @e5" --language bash -firecrawl interact --code "agent-browser snapshot -i" --language bash +firecrawl interact --code "agent-browser click @e5" --bash +firecrawl interact --code "agent-browser snapshot -i" --bash # 4. Stop the session when done firecrawl interact stop @@ -44,7 +44,9 @@ firecrawl interact stop | --------------------- | ------------------------------------------------- | | `--prompt ` | Natural language instruction (use this OR --code) | | `--code ` | Code to execute in the browser session | -| `--language ` | Language for code: bash, python, node | +| `--node` | Execute code as Node.js/Playwright (default) | +| `--python` | Execute code as Python/Playwright | +| `--bash` | Execute code as Bash | | `--timeout ` | Execution timeout (default: 30, max: 300) | | `--scrape-id ` | Target a specific scrape (default: last scrape) | | `-o, --output ` | Output file path | diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index b40101c643..c2290241ea 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -45,7 +45,7 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p | ------------------------ | ---------------------------------------------------------------- | | `-f, --format ` | Output formats: markdown, html, rawHtml, links, screenshot, json | | `-Q, --query ` | Ask a question about the page content (5 credits) | -| `-H` | Include HTTP headers in output | +| `-H, --html` | Output raw HTML (shortcut for `--format html`) | | `--only-main-content` | Strip nav, footer, sidebar β€” main content only | | `--wait-for ` | Wait for JS rendering before scraping | | `--include-tags ` | Only include these HTML tags | From cbbc62ea0d677e3adf31d9bf58fea68508e8e4c5 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 18:01:44 -0400 Subject: [PATCH 04/16] docs(skills): address review findings Make download examples safe for non-interactive flows and correct agent JSON guidance in the README. Include skill Markdown in Prettier scripts so formatting drift is caught. --- README.md | 4 ++-- package.json | 4 ++-- skills/firecrawl-download/SKILL.md | 6 +++--- skills/firecrawl-interact/SKILL.md | 6 +++--- skills/firecrawl-scrape/SKILL.md | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6576734427..68045f23a2 100644 --- a/README.md +++ b/README.md @@ -667,10 +667,10 @@ firecrawl agent "Find the top 5 competitors of Notion and their pricing" --wait firecrawl agent "Get all blog post titles and dates" --urls https://blog.example.com --max-credits 100 --wait # Use higher accuracy model for complex extraction -firecrawl agent "Extract detailed technical specifications" --model spark-1-pro --wait --pretty +firecrawl agent "Extract detailed technical specifications" --model spark-1-pro --wait --json --pretty # Save structured results to file -firecrawl agent "Extract contact information" --schema-file ./contact-schema.json --wait -o contacts.json --pretty +firecrawl agent "Extract contact information" --schema-file ./contact-schema.json --wait --json -o contacts.json --pretty # Check job status without waiting firecrawl agent abc123-def456-... --json diff --git a/package.json b/package.json index 097a4ee0e5..0aec596392 100644 --- a/package.json +++ b/package.json @@ -14,8 +14,8 @@ "clean": "rm -rf dist", "prepublishOnly": "pnpm run build", "prepare": "husky", - "format": "prettier --write \"src/**/*.{ts,json}\" \"*.{json,md}\"", - "format:check": "prettier --check \"src/**/*.{ts,json}\" \"*.{json,md}\"", + "format": "prettier --write \"src/**/*.{ts,json}\" \"skills/**/*.md\" \"*.{json,md}\"", + "format:check": "prettier --check \"src/**/*.{ts,json}\" \"skills/**/*.md\" \"*.{json,md}\"", "type-check": "tsc --noEmit", "test:watch": "vitest", "test": "vitest run", diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index 07cd43cdf3..3dab0a7048 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -11,7 +11,7 @@ allowed-tools: > **Experimental.** `download` is available under the `firecrawl x` command group. -Maps the site first to discover pages, then scrapes each one into nested directories under `.firecrawl/`. All scrape options work with download. Always pass `-y` to skip the confirmation prompt. +Maps the site first to discover pages, then scrapes each one into nested directories under `.firecrawl/`. Supported scrape options are listed below. Always pass `-y` to skip the confirmation prompt. ## When to use @@ -33,10 +33,10 @@ firecrawl x download https://docs.example.com --format markdown,links --screensh # Creates per page: index.md + links.txt + screenshot.png # Filter to specific sections -firecrawl x download https://docs.example.com --include-paths "/features,/sdks" +firecrawl x download https://docs.example.com --include-paths "/features,/sdks" -y # Skip translations -firecrawl x download https://docs.example.com --exclude-paths "/zh,/ja,/fr,/es,/pt-BR" +firecrawl x download https://docs.example.com --exclude-paths "/zh,/ja,/fr,/es,/pt-BR" -y # Full combo firecrawl x download https://docs.example.com \ diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index ed66dd6da1..203fcea8f1 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -44,9 +44,9 @@ firecrawl interact stop | --------------------- | ------------------------------------------------- | | `--prompt ` | Natural language instruction (use this OR --code) | | `--code ` | Code to execute in the browser session | -| `--node` | Execute code as Node.js/Playwright (default) | -| `--python` | Execute code as Python/Playwright | -| `--bash` | Execute code as Bash | +| `--node` | Execute code as Node.js/Playwright (default) | +| `--python` | Execute code as Python/Playwright | +| `--bash` | Execute code as Bash | | `--timeout ` | Execution timeout (default: 30, max: 300) | | `--scrape-id ` | Target a specific scrape (default: last scrape) | | `-o, --output ` | Output file path | diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index c2290241ea..3e333c2ae5 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -45,7 +45,7 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p | ------------------------ | ---------------------------------------------------------------- | | `-f, --format ` | Output formats: markdown, html, rawHtml, links, screenshot, json | | `-Q, --query ` | Ask a question about the page content (5 credits) | -| `-H, --html` | Output raw HTML (shortcut for `--format html`) | +| `-H, --html` | Output raw HTML (shortcut for `--format html`) | | `--only-main-content` | Strip nav, footer, sidebar β€” main content only | | `--wait-for ` | Wait for JS rendering before scraping | | `--include-tags ` | Only include these HTML tags | From b1c12404f5384caba22231e474d644a3d10e605e Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 16:14:48 -0400 Subject: [PATCH 05/16] docs(skills): correct behavior claims --- skills/firecrawl-agent/SKILL.md | 41 ++++++++++++++++++++++-------- skills/firecrawl-download/SKILL.md | 6 +++-- skills/firecrawl-interact/SKILL.md | 17 ++++++++----- skills/firecrawl-parse/SKILL.md | 18 ++++++------- skills/firecrawl-scrape/SKILL.md | 26 +++++++++---------- skills/firecrawl-search/SKILL.md | 4 +-- 6 files changed, 68 insertions(+), 44 deletions(-) diff --git a/skills/firecrawl-agent/SKILL.md b/skills/firecrawl-agent/SKILL.md index a36462cf2e..301909e93f 100644 --- a/skills/firecrawl-agent/SKILL.md +++ b/skills/firecrawl-agent/SKILL.md @@ -30,19 +30,38 @@ firecrawl agent "extract products" --schema '{"type":"object","properties":{"nam firecrawl agent "get feature list" --urls "" --wait --json -o .firecrawl/features.json ``` +## Job IDs + +Without `--wait`, the command returns a job ID. A UUID positional argument is auto-detected as a status check: + +```bash +# Check once (equivalent to adding --status) +firecrawl agent "" + +# Wait on an existing job, polling every 10 seconds for up to 5 minutes +firecrawl agent "" --wait --poll-interval 10 --timeout 300 + +# Cancel an active job +firecrawl agent "" --cancel +``` + ## Options -| Option | Description | -| ---------------------- | ----------------------------------------------------- | -| `--urls ` | Starting URLs for the agent | -| `--model ` | Model to use: spark-1-mini or spark-1-pro | -| `--schema ` | JSON schema for structured output | -| `--schema-file ` | Path to JSON schema file | -| `--max-credits ` | Credit limit for this agent run | -| `--wait` | Wait for agent to complete | -| `--json` | Output as JSON | -| `--pretty` | Pretty print JSON (`--wait` results require `--json`) | -| `-o, --output ` | Output file path | +| Option | Description | +| --------------------------- | ----------------------------------------------------- | +| `--urls ` | Starting URLs for the agent | +| `--model ` | Model to use: spark-1-mini or spark-1-pro | +| `--schema ` | JSON schema for structured output | +| `--schema-file ` | Path to JSON schema file | +| `--max-credits ` | Credit limit for this agent run | +| `--status` | Check a job ID's status | +| `--cancel` | Cancel an active job ID | +| `--wait` | Wait for agent to complete | +| `--poll-interval ` | Polling interval while waiting (default: 5 seconds) | +| `--timeout ` | Stop waiting after this duration (default: none) | +| `--json` | Output as JSON | +| `--pretty` | Pretty print JSON (`--wait` results require `--json`) | +| `-o, --output ` | Output file path | ## Tips diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index 3dab0a7048..cddf13f57c 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -11,7 +11,7 @@ allowed-tools: > **Experimental.** `download` is available under the `firecrawl x` command group. -Maps the site first to discover pages, then scrapes each one into nested directories under `.firecrawl/`. Supported scrape options are listed below. Always pass `-y` to skip the confirmation prompt. +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. Supported scrape options are listed below. Always pass `-y` to skip the confirmation prompt. ## When to use @@ -58,7 +58,9 @@ firecrawl x download https://docs.example.com \ | `--allow-subdomains` | Include subdomain pages | | `-y` | Skip confirmation prompt (always use in automated flows) | -## Scrape options (all work with download) +## Supported scrape options + +Only the options listed below are supported: `-f `, `-H`, `-S`, `--screenshot`, `--full-page-screenshot`, `--only-main-content`, `--include-tags`, `--exclude-tags`, `--wait-for`, `--max-age`, `--country`, `--languages` diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index 203fcea8f1..e389b1b8c1 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -25,14 +25,17 @@ Interact with scraped pages in a live browser session. Scrape a page first, then # 1. Scrape a page (scrape ID is saved automatically) firecrawl scrape "" -# 2. Interact with the page using natural language -firecrawl interact --prompt "Click the login button" -firecrawl interact --prompt "Fill in the email field with test@example.com" -firecrawl interact --prompt "Extract the pricing table" +# 2. Interact with the page using a positional prompt +firecrawl interact "Click the login button" +firecrawl interact "Fill in the email field with test@example.com" +firecrawl interact "Extract the pricing table" + +# A UUID first argument is auto-detected as the scrape ID +firecrawl interact "" "Extract the pricing table" # 3. Or use code for precise control -firecrawl interact --code "agent-browser click @e5" --bash -firecrawl interact --code "agent-browser snapshot -i" --bash +firecrawl interact --code "click @e5" --bash +firecrawl interact --code "snapshot -i" --bash # 4. Stop the session when done firecrawl interact stop @@ -74,7 +77,7 @@ firecrawl scrape "https://app.example.com" --profile my-app --no-save-changes ## Tips - Always scrape first β€” `interact` requires a scrape ID from a previous `firecrawl scrape` call -- The scrape ID is saved automatically, so you don't need `--scrape-id` for subsequent interact calls +- The scrape ID is saved automatically, so you don't need `--scrape-id` for subsequent interact calls. Saved sessions may expire after about 10 minutes; re-scrape if the CLI warns that the session is stale - Use `firecrawl interact stop` to free resources when done - For parallel work, scrape multiple pages and interact with each using `--scrape-id` diff --git a/skills/firecrawl-parse/SKILL.md b/skills/firecrawl-parse/SKILL.md index eeec7c2c06..be483b33ba 100644 --- a/skills/firecrawl-parse/SKILL.md +++ b/skills/firecrawl-parse/SKILL.md @@ -9,7 +9,7 @@ allowed-tools: # firecrawl parse -Turn a local document into clean markdown on disk. Supports **PDF, DOCX, DOC, ODT, RTF, XLSX, XLS, HTML/HTM/XHTML**. +Turn a local document into clean markdown on disk. Supports **PDF, DOCX, DOC, ODT, RTF, XLSX, XLS, HTML/HTM**. ## When to use @@ -39,14 +39,14 @@ Then `head`, `grep`, `rg` etc., or incrementally read the file - don't load the ## Options -| Option | Description | -| ---------------------- | --------------------------------------- | -| `-S, --summary` | AI-generated summary | -| `-Q, --query ` | Ask a question about the parsed content | -| `-o, --output ` | Output file path β€” **always use this** | -| `-f, --format ` | `markdown` (default), `html`, `summary` | -| `--timeout ` | Timeout for the parse job | -| `--timing` | Show request duration | +| Option | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `-S, --summary` | AI-generated summary | +| `-Q, --query ` | Ask a question about the parsed content | +| `-o, --output ` | Output file path β€” **always use this** | +| `-f, --format ` | Comma-separated: `markdown`, `html`, `rawHtml`, `links`, `images`, `summary`, `json`, `attributes`. Multiple formats output JSON | +| `--timeout ` | Timeout for the parse job | +| `--timing` | Show request duration | ## Tips diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index 3e333c2ae5..b08efa8b78 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -29,7 +29,7 @@ firecrawl scrape "" --only-main-content -o .firecrawl/page.md # Wait for JS to render, then scrape firecrawl scrape "" --wait-for 3000 -o .firecrawl/page.md -# Multiple URLs (each saved to .firecrawl/) +# Multiple URLs (markdown only; each saved to .firecrawl/; -o is ignored) firecrawl scrape https://example.com https://example.com/blog https://example.com/docs # Get markdown and links together @@ -41,23 +41,23 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p ## Options -| Option | Description | -| ------------------------ | ---------------------------------------------------------------- | -| `-f, --format ` | Output formats: markdown, html, rawHtml, links, screenshot, json | -| `-Q, --query ` | Ask a question about the page content (5 credits) | -| `-H, --html` | Output raw HTML (shortcut for `--format html`) | -| `--only-main-content` | Strip nav, footer, sidebar β€” main content only | -| `--wait-for ` | Wait for JS rendering before scraping | -| `--include-tags ` | Only include these HTML tags | -| `--exclude-tags ` | Exclude these HTML tags | -| `--redact-pii` | Redact personally identifiable information from output | -| `-o, --output ` | Output file path | +| Option | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `-f, --format ` | Output formats: markdown, html, rawHtml, links, images, screenshot, summary, changeTracking, json, attributes, branding | +| `-Q, --query ` | Ask a question about the page content (5 credits) | +| `-H, --html` | Output raw HTML (shortcut for `--format html`) | +| `--only-main-content` | Strip nav, footer, sidebar β€” main content only | +| `--wait-for ` | Wait for JS rendering before scraping | +| `--include-tags ` | Only include these HTML tags | +| `--exclude-tags ` | Exclude these HTML tags | +| `--redact-pii` | Redact personally identifiable information from output | +| `-o, --output ` | Output file path | ## Tips - **Prefer plain scrape over `--query`.** Scrape to a file, then use `grep`, `head`, or read the markdown directly β€” you can search and reason over the full content yourself. Use `--query` only when you want a single targeted answer without saving the page (costs 5 extra credits). - **Try scrape before interact.** Scrape handles static pages and JS-rendered SPAs. Only escalate to `interact` when you need interaction (clicks, form fills, pagination). -- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. +- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. This mode only saves usable markdown; other formats are JSON-stringified into `.md` files, and `-o` is ignored. - Single format outputs raw content. Multiple formats (e.g., `--format markdown,links`) output JSON. - Always quote URLs β€” shell interprets `?` and `&` as special characters. - Naming convention: `.firecrawl/{site}-{path}.md` diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index eedb318214..193de48a59 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -135,10 +135,10 @@ Search costs 2 credits. After you've actually used the results (or decided they - **Idempotent:** re-submitting for the same search id returns success but no extra refund. - **`--silent &`** is the right pattern β€” exit code 0 even on failure, so a rejected/expired call never crashes your pipeline. -Read the search response's `id`: +Verify the search returned results before reading its `id`. Zero-result searches do not write the output file, so never send feedback from a missing or stale file. ```bash -SEARCH_ID=$(jq -r '.id' .firecrawl/search-react-hooks.json) +SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json) ``` Then send feedback. Pick the rating that matches what actually happened: From 94a9e2795434a113be602c96aa935c4925baade5 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 16:24:25 -0400 Subject: [PATCH 06/16] docs(skills): clarify multi-URL scrape drops non-markdown formats --- skills/firecrawl-scrape/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index b08efa8b78..48898ffb41 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -57,7 +57,7 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p - **Prefer plain scrape over `--query`.** Scrape to a file, then use `grep`, `head`, or read the markdown directly β€” you can search and reason over the full content yourself. Use `--query` only when you want a single targeted answer without saving the page (costs 5 extra credits). - **Try scrape before interact.** Scrape handles static pages and JS-rendered SPAs. Only escalate to `interact` when you need interaction (clicks, form fills, pagination). -- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. This mode only saves usable markdown; other formats are JSON-stringified into `.md` files, and `-o` is ignored. +- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. This mode only saves markdown; if markdown isn't requested, the whole response is JSON-stringified into the `.md` file (other formats are otherwise dropped), and `-o` is ignored. - Single format outputs raw content. Multiple formats (e.g., `--format markdown,links`) output JSON. - Always quote URLs β€” shell interprets `?` and `&` as special characters. - Naming convention: `.firecrawl/{site}-{path}.md` From d450135f8225c310782c170853e4cf3df18bd862 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 18:27:14 -0400 Subject: [PATCH 07/16] docs(skills): fix remaining wrong claims found in review Adversarial review against src/ surfaced wrong claims that survived the first audit pass, in the same files this PR touches: - scrape: -H is --html (raw HTML shortcut), not HTTP headers - interact: --language does not exist; the CLI uses --node/--python/--bash - download: the command is only registered as 'firecrawl x download' (experimental), so all examples used a nonexistent invocation; the 'only these options' list omitted --lockdown; the wizard example is TTY-only and blocks agents without -y - search: spell out guard-failure behavior and split the missing-file vs stale-file hazards - scrape/agent: reword confusing multi-URL parenthetical and dedupe the --wait tip - cli: mirror the guarded jq search-id recipe so it doesn't drift from the corrected search skill --- skills/firecrawl-agent/SKILL.md | 2 +- skills/firecrawl-cli/SKILL.md | 3 ++- skills/firecrawl-download/SKILL.md | 6 +++--- skills/firecrawl-interact/SKILL.md | 18 ++++++++---------- skills/firecrawl-scrape/SKILL.md | 2 +- skills/firecrawl-search/SKILL.md | 4 ++-- 6 files changed, 17 insertions(+), 18 deletions(-) diff --git a/skills/firecrawl-agent/SKILL.md b/skills/firecrawl-agent/SKILL.md index 301909e93f..5258fa8730 100644 --- a/skills/firecrawl-agent/SKILL.md +++ b/skills/firecrawl-agent/SKILL.md @@ -65,7 +65,7 @@ firecrawl agent "" --cancel ## Tips -- Always use `--wait` to get results inline. Without it, returns a job ID. +- Use `--wait` for inline results; without it you get a job ID (see [Job IDs](#job-ids)). - Use `--schema` for predictable, structured output β€” otherwise the agent returns freeform data. - Agent runs consume more credits than simple scrapes. Use `--max-credits` to cap spending. - For simple single-page extraction, prefer `scrape` β€” it's faster and cheaper. diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index 75c1b09ef6..6ac50f6f66 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -267,7 +267,8 @@ jq -r '.data.web[] | "\(.title): \(.url)"' .firecrawl/search.json Search costs 2 credits per call. **After you finish using a search result**, send structured feedback in the background. The first feedback per search id refunds 1 credit and feeds search-quality improvements. ```bash -SEARCH_ID=$(jq -r '.id' .firecrawl/search-react-hooks.json) +# Guard: zero-result searches write no output file, so verify before reading the id +SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json) firecrawl search-feedback "$SEARCH_ID" \ --rating good \ diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index cddf13f57c..b92db3f286 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -7,7 +7,7 @@ allowed-tools: - Bash(npx firecrawl-cli *) --- -# firecrawl download +# firecrawl download (invoked as `firecrawl x download`) > **Experimental.** `download` is available under the `firecrawl x` command group. @@ -22,7 +22,7 @@ Maps the site origin first to discover pages, then scrapes each one into nested ## Quick start ```bash -# Interactive wizard (picks format, screenshots, paths for you) +# Interactive wizard (humans at a TTY only β€” agents must pass -y or the command blocks on a prompt) firecrawl x download https://docs.example.com # With screenshots @@ -62,7 +62,7 @@ firecrawl x download https://docs.example.com \ Only the options listed below are supported: -`-f `, `-H`, `-S`, `--screenshot`, `--full-page-screenshot`, `--only-main-content`, `--include-tags`, `--exclude-tags`, `--wait-for`, `--max-age`, `--country`, `--languages` +`-f `, `-H`, `-S`, `--lockdown`, `--screenshot`, `--full-page-screenshot`, `--only-main-content`, `--include-tags`, `--exclude-tags`, `--wait-for`, `--max-age`, `--country`, `--languages` ## See also diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index e389b1b8c1..fe15f06d00 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -43,16 +43,14 @@ firecrawl interact stop ## Options -| Option | Description | -| --------------------- | ------------------------------------------------- | -| `--prompt ` | Natural language instruction (use this OR --code) | -| `--code ` | Code to execute in the browser session | -| `--node` | Execute code as Node.js/Playwright (default) | -| `--python` | Execute code as Python/Playwright | -| `--bash` | Execute code as Bash | -| `--timeout ` | Execution timeout (default: 30, max: 300) | -| `--scrape-id ` | Target a specific scrape (default: last scrape) | -| `-o, --output ` | Output file path | +| Option | Description | +| -------------------------------- | ------------------------------------------------- | +| `--prompt ` | Natural language instruction (use this OR --code) | +| `--code ` | Code to execute in the browser session | +| `--node` / `--python` / `--bash` | Language for `--code` (default: node) | +| `--timeout ` | Execution timeout (default: 30, max: 300) | +| `--scrape-id ` | Target a specific scrape (default: last scrape) | +| `-o, --output ` | Output file path | ## Profiles diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index 48898ffb41..a957f9e176 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -57,7 +57,7 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p - **Prefer plain scrape over `--query`.** Scrape to a file, then use `grep`, `head`, or read the markdown directly β€” you can search and reason over the full content yourself. Use `--query` only when you want a single targeted answer without saving the page (costs 5 extra credits). - **Try scrape before interact.** Scrape handles static pages and JS-rendered SPAs. Only escalate to `interact` when you need interaction (clicks, form fills, pagination). -- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. This mode only saves markdown; if markdown isn't requested, the whole response is JSON-stringified into the `.md` file (other formats are otherwise dropped), and `-o` is ignored. +- Multiple URLs are scraped concurrently β€” check `firecrawl --status` for your concurrency limit. This mode saves markdown only and ignores `-o`; other requested formats are dropped. If markdown wasn't requested, the whole JSON response is written into the `.md` file. - Single format outputs raw content. Multiple formats (e.g., `--format markdown,links`) output JSON. - Always quote URLs β€” shell interprets `?` and `&` as special characters. - Naming convention: `.firecrawl/{site}-{path}.md` diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 193de48a59..6d75557572 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -135,13 +135,13 @@ Search costs 2 credits. After you've actually used the results (or decided they - **Idempotent:** re-submitting for the same search id returns success but no extra refund. - **`--silent &`** is the right pattern β€” exit code 0 even on failure, so a rejected/expired call never crashes your pipeline. -Verify the search returned results before reading its `id`. Zero-result searches do not write the output file, so never send feedback from a missing or stale file. +Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Only send feedback when this guard succeeds: ```bash SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json) ``` -Then send feedback. Pick the rating that matches what actually happened: +If the guard fails (non-zero exit: missing file or zero results), skip feedback. Otherwise pick the rating that matches what actually happened: ```bash # Results were useful, with notes on what was still missing From 6a9f57dc8432ec7f7ae4535465148777fd140d53 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Mon, 17 Aug 2026 16:14:21 -0400 Subject: [PATCH 08/16] docs(skills): clarify auth and API-side behavior --- skills/firecrawl-cli/SKILL.md | 8 ++++++-- skills/firecrawl-crawl/SKILL.md | 8 +++++--- skills/firecrawl-download/SKILL.md | 2 ++ skills/firecrawl-interact/SKILL.md | 2 +- skills/firecrawl-map/SKILL.md | 4 +++- skills/firecrawl-monitor/SKILL.md | 9 ++++++--- skills/firecrawl-parse/SKILL.md | 2 +- skills/firecrawl-scrape/SKILL.md | 2 +- skills/firecrawl-search/SKILL.md | 2 +- 9 files changed, 26 insertions(+), 13 deletions(-) diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index 6ac50f6f66..ff985568ca 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -135,7 +135,7 @@ firecrawl monitor update --state paused firecrawl monitor delete ``` -Schedules accept cron (`--cron "*/5 * * * *"`) or natural language (`--schedule "every 5 minutes"`). Minimum interval is 5 minutes. Targets are `--page ` for one page, `--scrape-urls a,b,c` for multiple scrape URLs, or `--crawl-url ` for a whole-site crawl each check. Use `--goal` for flag-based monitor creation, or include `"goal": "..."` in JSON payloads. Note: `--state` (not `--status`) sets active/paused; `--page-status` (not `--status`) filters page results on `check` β€” avoids collision with the global `--status` flag. Monitoring is not available for zero-data-retention teams. +Schedules accept cron (`--cron "*/5 * * * *"`) or natural language (`--schedule "every 5 minutes"`). Minimum interval is 5 minutes. Targets are `--page ` for one page, `--scrape-urls a,b,c` for multiple scrape URLs, `--crawl-url ` for a whole-site crawl each check, or `--queries ` plus required `--goal` for web-search monitors; tune web search with `--search-window` and `--max-results`. Use `--goal` for flag-based monitor creation, or include `"goal": "..."` in JSON payloads. Note: `--state` (not `--status`) sets active/paused; `--page-status` (not `--status`) filters page results on `check` β€” avoids collision with the global `--status` flag. Monitoring is not available for zero-data-retention teams. **JSON-mode change tracking:** By default monitors diff each page's markdown and you get a unified text diff back. When you care about **specific structured fields** (price, headline, in-stock flag, items in a list) instead of the whole page, add a `changeTracking` format with `modes: ["json"]` and a JSON schema to the target's `scrapeOptions.formats`. The flag-based form doesn't cover this β€” pass a JSON body via file or stdin: @@ -194,7 +194,9 @@ The `check` response then carries a per-field diff (paths like `plans[0].price`) }, "snapshot": { "json": { - "plans": [/* current full extraction */] + "plans": [ + /* current full extraction */ + ] } } } @@ -316,6 +318,8 @@ For interact, scrape multiple pages and interact with each independently using t ## Credit Usage +Requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login. + ```bash firecrawl credit-usage firecrawl credit-usage --json --pretty -o .firecrawl/credits.json diff --git a/skills/firecrawl-crawl/SKILL.md b/skills/firecrawl-crawl/SKILL.md index db001e57bd..05c2e00f76 100644 --- a/skills/firecrawl-crawl/SKILL.md +++ b/skills/firecrawl-crawl/SKILL.md @@ -11,11 +11,13 @@ allowed-tools: Bulk extract content from a website. Crawls pages following links up to a depth/limit. +**Prerequisite:** `crawl` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login. + ## When to use - You need content from many pages on a site (e.g., all `/docs/`) - You want to extract an entire site section -- Step 4 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ **crawl** β†’ interact +- Step 4 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ **crawl** β†’ monitor β†’ interact ## Quick start @@ -47,9 +49,9 @@ firecrawl crawl ## Tips -- Always use `--wait` when you need the results immediately. Without it, crawl returns a job ID for async polling. +- Always use `--wait` when you need the results immediately. It has no default timeout; use `--timeout ` to bound polling. Without `--wait`, crawl returns a job ID for async polling. - Use `--include-paths` to scope the crawl β€” don't crawl an entire site when you only need one section. -- Crawl consumes credits per page. Check `firecrawl credit-usage` before large crawls. +- Crawl consumes credits per page. Check `firecrawl credit-usage` before large crawls (`credit-usage` requires authentication). ## See also diff --git a/skills/firecrawl-download/SKILL.md b/skills/firecrawl-download/SKILL.md index b92db3f286..ece43a10d5 100644 --- a/skills/firecrawl-download/SKILL.md +++ b/skills/firecrawl-download/SKILL.md @@ -11,6 +11,8 @@ allowed-tools: > **Experimental.** `download` is available under the `firecrawl x` command group. +**Prerequisite:** `download` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login. + 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. Supported scrape options are listed below. Always pass `-y` to skip the confirmation prompt. ## When to use diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index fe15f06d00..d8f82cd01f 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -16,7 +16,7 @@ Interact with scraped pages in a live browser session. Scrape a page first, then - Content requires interaction: clicks, form fills, pagination, login - `scrape` failed because content is behind JavaScript interaction - You need to navigate a multi-step flow -- Last resort in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ **interact** +- Last resort in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ **interact** - **Never use interact for web searches** β€” use `search` instead ## Quick start diff --git a/skills/firecrawl-map/SKILL.md b/skills/firecrawl-map/SKILL.md index aa949c56fe..9edeb852ed 100644 --- a/skills/firecrawl-map/SKILL.md +++ b/skills/firecrawl-map/SKILL.md @@ -11,11 +11,13 @@ allowed-tools: Discover URLs on a site. Use `--search` to find a specific page within a large site. +**Prerequisite:** `map` requires authentication (no keyless free tier); without credentials the CLI prompts an interactive login. + ## When to use - You need to find a specific subpage on a large site - You want a list of all URLs on a site before scraping or crawling -- Step 3 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ **map** β†’ crawl β†’ interact +- Step 3 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ **map** + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start diff --git a/skills/firecrawl-monitor/SKILL.md b/skills/firecrawl-monitor/SKILL.md index 79f28a95b9..55a33ce458 100644 --- a/skills/firecrawl-monitor/SKILL.md +++ b/skills/firecrawl-monitor/SKILL.md @@ -31,7 +31,7 @@ The first three watch URLs you already have. **Web search** is the odd one out - **Monitoring the web** for _new_ results rather than changes to a known page β€” new launches, funding rounds, papers, news, releases, or brand mentions surfaced by search across the whole web (a **web monitor**: `--queries` + `--goal`) - "Alert me when...", "notify me when...", "email me if...", "send a webhook when...", "ping me if X changes", "track this page", "monitor the web for...", "watch for new..." - Anywhere the user would otherwise wire up cron + a scraper + a diff library + SMTP themselves -- Step 5 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ **monitor** β†’ interact +- Step 5 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ **monitor** β†’ interact **Bias toward `monitor`** whenever the request implies notifications or recurrence. A single page read once = `scrape`. A single page where the user wants to be told when it changes = `monitor --page --goal "..." --email|--webhook-url ...`. @@ -114,10 +114,13 @@ Subcommands: `create | list | get | update | delete | run | checks | check`. | `--retention-days ` | Snapshot retention window | | `--state ` | `active` or `paused` (update only β€” use `--state`, not `--status`) | | `--page-status ` | Filter `check` results: `same`, `new`, `changed`, `removed`, `error` | +| `--limit ` | Max results (`list`, `checks`) or page results (`check`) | +| `--offset ` | Result offset (`list`, `checks`) | +| `--skip ` | Page-result offset (`check`) | | `-o, --output ` | Output file path | | `--pretty` | Pretty-print JSON output | -Minimum schedule interval is **15 minutes**. Monitoring is **not available for zero-data-retention teams**. +Minimum schedule interval is **5 minutes**. Monitoring is **not available for zero-data-retention teams**. ## Web monitors (monitor the web) @@ -148,7 +151,7 @@ For a web monitor, **queries control recall** (what the search retrieves) and ** - One query per **distinct** subject. Several facets of one subject = one query; only split for genuinely separate entities (e.g. "OpenAI, Anthropic, and Google"). - No `site:` operators in queries β€” use `--include-domains` / `--exclude-domains`. -**What good looks like:** a healthy web monitor mostly returns `new: 0` and alerts only on genuinely new, on-goal results. If most results come back `ignored`, the queries pull noise the goal rejects β€” tighten the queries. If a topic returns nothing for long stretches, the queries are too narrow or `--search-window` too tight β€” broaden them. If the user dismisses alerts, the goal is too broad β€” add an intent-specific `Ignore ...`. The aim is high precision with enough recall: every alert worth acting on, nothing real missed. +**What good looks like:** a healthy web monitor mostly returns `new: 0` and alerts only on genuinely new, on-goal results. If many retrieved results are off-goal, the queries pull noise the goal rejects β€” tighten the queries. If a topic returns nothing for long stretches, the queries are too narrow or `--search-window` too tight β€” broaden them. If the user dismisses alerts, the goal is too broad β€” add an intent-specific `Ignore ...`. The aim is high precision with enough recall: every alert worth acting on, nothing real missed. ## Writing a good `--goal` diff --git a/skills/firecrawl-parse/SKILL.md b/skills/firecrawl-parse/SKILL.md index be483b33ba..5f29816b52 100644 --- a/skills/firecrawl-parse/SKILL.md +++ b/skills/firecrawl-parse/SKILL.md @@ -54,7 +54,7 @@ Then `head`, `grep`, `rg` etc., or incrementally read the file - don't load the - Max upload size: **50 MB** per file. - Credits: ~1 per PDF page; HTML is 1 flat. - Check `.firecrawl/` before re-parsing the same file. -- To check your credit balance (recommended for batch processing and similar workflows), use the `firecrawl credit-usage` command. +- To check your credit balance (recommended for batch processing and similar workflows), use `firecrawl credit-usage` (requires authentication). ## See also diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index a957f9e176..1a35b87c1f 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -15,7 +15,7 @@ Scrape one or more URLs. Returns clean, LLM-optimized markdown. Multiple URLs ar - You have a specific URL and want its content - The page is static or JS-rendered (SPA) -- Step 2 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ **scrape** β†’ map β†’ crawl β†’ interact +- Step 2 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ **scrape** β†’ map + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 6d75557572..03152effe8 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -16,7 +16,7 @@ Web search with optional content scraping. Returns search results as JSON, optio - You don't have a specific URL yet - You need to find pages, answer questions, or discover sources - You need research papers β€” see [Paper search](#paper-search), which routes to `firecrawl research`, not to `search --categories research` -- First step in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map β†’ crawl β†’ interact +- First step in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start From 9e2f5311daffa2372062b260040c3e948bc5aed5 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 13:54:50 -0400 Subject: [PATCH 09/16] docs(skills): make the search-feedback guard actually skip on failure A bare SEARCH_ID=$(jq -er ...) assignment does not stop the follow-on search-feedback call when the guard fails (missing file or zero results), so it fired with an empty id. Wrap the feedback call in the guard conditional in both mirrored snippets. --- skills/firecrawl-cli/SKILL.md | 19 ++++++++++--------- skills/firecrawl-search/SKILL.md | 6 ++++-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl-cli/SKILL.md index ff985568ca..c26d2ab4db 100644 --- a/skills/firecrawl-cli/SKILL.md +++ b/skills/firecrawl-cli/SKILL.md @@ -269,15 +269,16 @@ jq -r '.data.web[] | "\(.title): \(.url)"' .firecrawl/search.json Search costs 2 credits per call. **After you finish using a search result**, send structured feedback in the background. The first feedback per search id refunds 1 credit and feeds search-quality improvements. ```bash -# Guard: zero-result searches write no output file, so verify before reading the id -SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json) - -firecrawl search-feedback "$SEARCH_ID" \ - --rating good \ - --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Authoritative"}]' \ - --missing-content '[{"topic":"useDeferredValue example"},{"topic":"Server Components hooks"}]' \ - --query-suggestions "Boost react.dev for react-hooks queries" \ - --silent & +# Guard: zero-result searches write no output file, so verify before reading the id. +# A failed guard (missing file or zero results) skips the feedback call entirely. +if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then + firecrawl search-feedback "$SEARCH_ID" \ + --rating good \ + --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Authoritative"}]' \ + --missing-content '[{"topic":"useDeferredValue example"},{"topic":"Server Components hooks"}]' \ + --query-suggestions "Boost react.dev for react-hooks queries" \ + --silent & +fi ``` The most useful field is `--missing-content`: an _array_ of specific pieces of content you expected to find but didn't. Use one entry per missing topic. Bad/partial feedback with detailed `--missing-content` is just as valuable as good feedback. diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 03152effe8..e57615ae39 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -138,10 +138,12 @@ Search costs 2 credits. After you've actually used the results (or decided they Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Only send feedback when this guard succeeds: ```bash -SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json) +if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then + : # guard passed β€” send exactly one of the feedback calls below +fi ``` -If the guard fails (non-zero exit: missing file or zero results), skip feedback. Otherwise pick the rating that matches what actually happened: +A failed guard (non-zero exit: missing file or zero results) must skip feedback, so call `search-feedback` only inside this conditional β€” a bare assignment leaves `SEARCH_ID` empty and the call would still fire. Pick the rating that matches what actually happened: ```bash # Results were useful, with notes on what was still missing From 5f94d6fb6f3e6370dc86afcf18641c13d0057696 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 14:27:08 -0400 Subject: [PATCH 10/16] docs(skills): rename firecrawl-cli skill folder to match its frontmatter name The installer copies each skill to ~/.agents/skills//, and the router skill is named "firecrawl", so ../firecrawl-cli/SKILL.md links 404ed after install. Rename the folder to skills/firecrawl/ so the folder and frontmatter agree and cross-skill links resolve both in-repo and installed. --- skills/firecrawl-crawl/SKILL.md | 2 +- skills/firecrawl-interact/SKILL.md | 2 +- skills/firecrawl-map/SKILL.md | 2 +- skills/firecrawl-monitor/SKILL.md | 4 ++-- skills/firecrawl-scrape/SKILL.md | 2 +- skills/firecrawl-search/SKILL.md | 4 ++-- skills/{firecrawl-cli => firecrawl}/SKILL.md | 0 skills/{firecrawl-cli => firecrawl}/rules/install.md | 0 skills/{firecrawl-cli => firecrawl}/rules/security.md | 0 9 files changed, 8 insertions(+), 8 deletions(-) rename skills/{firecrawl-cli => firecrawl}/SKILL.md (100%) rename skills/{firecrawl-cli => firecrawl}/rules/install.md (100%) rename skills/{firecrawl-cli => firecrawl}/rules/security.md (100%) diff --git a/skills/firecrawl-crawl/SKILL.md b/skills/firecrawl-crawl/SKILL.md index 05c2e00f76..1d99f48a54 100644 --- a/skills/firecrawl-crawl/SKILL.md +++ b/skills/firecrawl-crawl/SKILL.md @@ -17,7 +17,7 @@ Bulk extract content from a website. Crawls pages following links up to a depth/ - You need content from many pages on a site (e.g., all `/docs/`) - You want to extract an entire site section -- Step 4 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ **crawl** β†’ monitor β†’ interact +- Step 4 in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ scrape β†’ map + scrape β†’ **crawl** β†’ monitor β†’ interact ## Quick start diff --git a/skills/firecrawl-interact/SKILL.md b/skills/firecrawl-interact/SKILL.md index d8f82cd01f..cbb731df9f 100644 --- a/skills/firecrawl-interact/SKILL.md +++ b/skills/firecrawl-interact/SKILL.md @@ -16,7 +16,7 @@ Interact with scraped pages in a live browser session. Scrape a page first, then - Content requires interaction: clicks, form fills, pagination, login - `scrape` failed because content is behind JavaScript interaction - You need to navigate a multi-step flow -- Last resort in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ **interact** +- Last resort in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ **interact** - **Never use interact for web searches** β€” use `search` instead ## Quick start diff --git a/skills/firecrawl-map/SKILL.md b/skills/firecrawl-map/SKILL.md index 9edeb852ed..1db2b456b4 100644 --- a/skills/firecrawl-map/SKILL.md +++ b/skills/firecrawl-map/SKILL.md @@ -17,7 +17,7 @@ Discover URLs on a site. Use `--search` to find a specific page within a large s - You need to find a specific subpage on a large site - You want a list of all URLs on a site before scraping or crawling -- Step 3 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ **map** + scrape β†’ crawl β†’ monitor β†’ interact +- Step 3 in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ scrape β†’ **map** + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start diff --git a/skills/firecrawl-monitor/SKILL.md b/skills/firecrawl-monitor/SKILL.md index 55a33ce458..511357a509 100644 --- a/skills/firecrawl-monitor/SKILL.md +++ b/skills/firecrawl-monitor/SKILL.md @@ -31,7 +31,7 @@ The first three watch URLs you already have. **Web search** is the odd one out - **Monitoring the web** for _new_ results rather than changes to a known page β€” new launches, funding rounds, papers, news, releases, or brand mentions surfaced by search across the whole web (a **web monitor**: `--queries` + `--goal`) - "Alert me when...", "notify me when...", "email me if...", "send a webhook when...", "ping me if X changes", "track this page", "monitor the web for...", "watch for new..." - Anywhere the user would otherwise wire up cron + a scraper + a diff library + SMTP themselves -- Step 5 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ **monitor** β†’ interact +- Step 5 in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ **monitor** β†’ interact **Bias toward `monitor`** whenever the request implies notifications or recurrence. A single page read once = `scrape`. A single page where the user wants to be told when it changes = `monitor --page --goal "..." --email|--webhook-url ...`. @@ -257,4 +257,4 @@ Use `modes: ["json", "git-diff"]` for **mixed mode** β€” you get both `diff.json - [firecrawl-scrape](../firecrawl-scrape/SKILL.md) β€” one-off scrape; escalate to `monitor` when checks become recurring - [firecrawl-crawl](../firecrawl-crawl/SKILL.md) β€” one-off crawl; pair with `--crawl-url` here for recurring crawl diffs -- [firecrawl-cli](../firecrawl-cli/SKILL.md) β€” top-level workflow guide +- [firecrawl-cli](../firecrawl/SKILL.md) β€” top-level workflow guide diff --git a/skills/firecrawl-scrape/SKILL.md b/skills/firecrawl-scrape/SKILL.md index 1a35b87c1f..519ffe12e0 100644 --- a/skills/firecrawl-scrape/SKILL.md +++ b/skills/firecrawl-scrape/SKILL.md @@ -15,7 +15,7 @@ Scrape one or more URLs. Returns clean, LLM-optimized markdown. Multiple URLs ar - You have a specific URL and want its content - The page is static or JS-rendered (SPA) -- Step 2 in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ **scrape** β†’ map + scrape β†’ crawl β†’ monitor β†’ interact +- Step 2 in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ **scrape** β†’ map + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index e57615ae39..456bbffc9a 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -16,7 +16,7 @@ Web search with optional content scraping. Returns search results as JSON, optio - You don't have a specific URL yet - You need to find pages, answer questions, or discover sources - You need research papers β€” see [Paper search](#paper-search), which routes to `firecrawl research`, not to `search --categories research` -- First step in the [workflow escalation pattern](../firecrawl-cli/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ interact +- First step in the [workflow escalation pattern](../firecrawl/SKILL.md): search β†’ scrape β†’ map + scrape β†’ crawl β†’ monitor β†’ interact ## Quick start @@ -90,7 +90,7 @@ Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms. `inspect-paper` returns canonical metadata for one id. Read hits with `jq -r '.results[] | .primaryId, .title' .firecrawl/papers.json`. -See [firecrawl-cli](../firecrawl-cli/SKILL.md) for how paper search fits the +See [firecrawl-cli](../firecrawl/SKILL.md) for how paper search fits the overall command routing. ## Options diff --git a/skills/firecrawl-cli/SKILL.md b/skills/firecrawl/SKILL.md similarity index 100% rename from skills/firecrawl-cli/SKILL.md rename to skills/firecrawl/SKILL.md diff --git a/skills/firecrawl-cli/rules/install.md b/skills/firecrawl/rules/install.md similarity index 100% rename from skills/firecrawl-cli/rules/install.md rename to skills/firecrawl/rules/install.md diff --git a/skills/firecrawl-cli/rules/security.md b/skills/firecrawl/rules/security.md similarity index 100% rename from skills/firecrawl-cli/rules/security.md rename to skills/firecrawl/rules/security.md From dbfe84c4cc0c901c5a68ed020cc3b747341fae1f Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:12:35 -0400 Subject: [PATCH 11/16] docs(skills): finish firecrawl skill rename and inline the feedback guard Update the .claude-plugin skill paths missed by the folder rename, and move the three search-feedback examples inside the guard conditional so copying any of them cannot bypass the zero-result check. --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- skills/firecrawl-search/SKILL.md | 62 +++++++++++++++----------------- 3 files changed, 30 insertions(+), 36 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4b7392f998..73e527ca23 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ "description": "Scrape, search, crawl, and map the web with a single command.", "skills": [ "./skills/firecrawl-agent", - "./skills/firecrawl-cli", + "./skills/firecrawl", "./skills/firecrawl-crawl", "./skills/firecrawl-download", "./skills/firecrawl-interact", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e59ca3ab1c..499f8cd18b 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -7,7 +7,7 @@ }, "skills": [ "./skills/firecrawl-agent", - "./skills/firecrawl-cli", + "./skills/firecrawl", "./skills/firecrawl-crawl", "./skills/firecrawl-download", "./skills/firecrawl-interact", diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 456bbffc9a..852abd0f2f 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -135,46 +135,40 @@ Search costs 2 credits. After you've actually used the results (or decided they - **Idempotent:** re-submitting for the same search id returns success but no extra refund. - **`--silent &`** is the right pattern β€” exit code 0 even on failure, so a rejected/expired call never crashes your pipeline. -Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Only send feedback when this guard succeeds: +Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Call `search-feedback` only inside this guard β€” a failed guard (non-zero exit: missing file or zero results) skips feedback, while a bare assignment would leave `SEARCH_ID` empty and still fire the call. Send exactly one of the calls below, picking the rating that matches what actually happened: ```bash if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then - : # guard passed β€” send exactly one of the feedback calls below + # Results were useful, with notes on what was still missing + firecrawl search-feedback "$SEARCH_ID" \ + --rating good \ + --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \ + --missing-content '[ + {"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}, + {"topic":"useTransition","description":"No coverage of useTransition for routing"} + ]' \ + --query-suggestions "Boost react.dev for queries about react hooks" \ + --silent & + + # Results were partially useful β€” multiple missing topics, one entry per topic + firecrawl search-feedback "$SEARCH_ID" \ + --rating partial \ + --missing-content '[ + {"topic":"useDeferredValue"}, + {"topic":"useTransition","description":"Need React 18+ examples"}, + {"topic":"Server Components hooks"} + ]' \ + --silent & + + # Quick form β€” repeat --missing-content or use comma-separated topics + firecrawl search-feedback "$SEARCH_ID" \ + --rating bad \ + --missing-content "official api reference: missing v2 endpoints" \ + --missing-content "code examples in python" \ + --silent & fi ``` -A failed guard (non-zero exit: missing file or zero results) must skip feedback, so call `search-feedback` only inside this conditional β€” a bare assignment leaves `SEARCH_ID` empty and the call would still fire. Pick the rating that matches what actually happened: - -```bash -# Results were useful, with notes on what was still missing -firecrawl search-feedback "$SEARCH_ID" \ - --rating good \ - --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \ - --missing-content '[ - {"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}, - {"topic":"useTransition","description":"No coverage of useTransition for routing"} - ]' \ - --query-suggestions "Boost react.dev for queries about react hooks" \ - --silent & - -# Results were partially useful β€” multiple missing topics, one entry per topic -firecrawl search-feedback "$SEARCH_ID" \ - --rating partial \ - --missing-content '[ - {"topic":"useDeferredValue"}, - {"topic":"useTransition","description":"Need React 18+ examples"}, - {"topic":"Server Components hooks"} - ]' \ - --silent & - -# Quick form β€” repeat --missing-content or use comma-separated topics -firecrawl search-feedback "$SEARCH_ID" \ - --rating bad \ - --missing-content "official api reference: missing v2 endpoints" \ - --missing-content "code examples in python" \ - --silent & -``` - **`--missing-content` accepts:** - JSON array of `{topic, description?}` objects (richest, preferred) From 561776fe233f364bfc300bc50b268575db880d44 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:16:06 -0400 Subject: [PATCH 12/16] docs(skills): update stale firecrawl-cli link labels to firecrawl --- skills/firecrawl-monitor/SKILL.md | 2 +- skills/firecrawl-search/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/firecrawl-monitor/SKILL.md b/skills/firecrawl-monitor/SKILL.md index 511357a509..5c2aa34964 100644 --- a/skills/firecrawl-monitor/SKILL.md +++ b/skills/firecrawl-monitor/SKILL.md @@ -257,4 +257,4 @@ Use `modes: ["json", "git-diff"]` for **mixed mode** β€” you get both `diff.json - [firecrawl-scrape](../firecrawl-scrape/SKILL.md) β€” one-off scrape; escalate to `monitor` when checks become recurring - [firecrawl-crawl](../firecrawl-crawl/SKILL.md) β€” one-off crawl; pair with `--crawl-url` here for recurring crawl diffs -- [firecrawl-cli](../firecrawl/SKILL.md) β€” top-level workflow guide +- [firecrawl](../firecrawl/SKILL.md) β€” top-level workflow guide diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 852abd0f2f..f9a322457c 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -90,7 +90,7 @@ Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms. `inspect-paper` returns canonical metadata for one id. Read hits with `jq -r '.results[] | .primaryId, .title' .firecrawl/papers.json`. -See [firecrawl-cli](../firecrawl/SKILL.md) for how paper search fits the +See [firecrawl](../firecrawl/SKILL.md) for how paper search fits the overall command routing. ## Options From adb47cc31d85d155d69b8f53ba4c57ca85356b1a Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:22:52 -0400 Subject: [PATCH 13/16] docs(skills): make only one feedback rating live in the guard example All three rating calls were live sequential commands inside the guard, so a literal copy-paste submitted three conflicting ratings for one search id. Keep the good-rating call live and show partial/bad as commented alternates, matching the "send exactly one" prose. --- skills/firecrawl-search/SKILL.md | 34 ++++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index f9a322457c..95f4ba0100 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -135,7 +135,7 @@ Search costs 2 credits. After you've actually used the results (or decided they - **Idempotent:** re-submitting for the same search id returns success but no extra refund. - **`--silent &`** is the right pattern β€” exit code 0 even on failure, so a rejected/expired call never crashes your pipeline. -Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Call `search-feedback` only inside this guard β€” a failed guard (non-zero exit: missing file or zero results) skips feedback, while a bare assignment would leave `SEARCH_ID` empty and still fire the call. Send exactly one of the calls below, picking the rating that matches what actually happened: +Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Call `search-feedback` only inside this guard β€” a failed guard (non-zero exit: missing file or zero results) skips feedback, while a bare assignment would leave `SEARCH_ID` empty and still fire the call. Send exactly one call per search; swap in the alternate rating that matches what actually happened: ```bash if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then @@ -150,22 +150,22 @@ if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search --query-suggestions "Boost react.dev for queries about react hooks" \ --silent & - # Results were partially useful β€” multiple missing topics, one entry per topic - firecrawl search-feedback "$SEARCH_ID" \ - --rating partial \ - --missing-content '[ - {"topic":"useDeferredValue"}, - {"topic":"useTransition","description":"Need React 18+ examples"}, - {"topic":"Server Components hooks"} - ]' \ - --silent & - - # Quick form β€” repeat --missing-content or use comma-separated topics - firecrawl search-feedback "$SEARCH_ID" \ - --rating bad \ - --missing-content "official api reference: missing v2 endpoints" \ - --missing-content "code examples in python" \ - --silent & + # Alternate β€” partially useful results: multiple missing topics, one entry per topic + # firecrawl search-feedback "$SEARCH_ID" \ + # --rating partial \ + # --missing-content '[ + # {"topic":"useDeferredValue"}, + # {"topic":"useTransition","description":"Need React 18+ examples"}, + # {"topic":"Server Components hooks"} + # ]' \ + # --silent & + + # Alternate β€” bad results, quick form: repeat --missing-content or use comma-separated topics + # firecrawl search-feedback "$SEARCH_ID" \ + # --rating bad \ + # --missing-content "official api reference: missing v2 endpoints" \ + # --missing-content "code examples in python" \ + # --silent & fi ``` From c111a31d4bf9fbf7581c179193311c0553c1d08e Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:27:54 -0400 Subject: [PATCH 14/16] docs(skills): collapse feedback example to one default call Replace the three parallel rating examples (latterly commented alternates) with a single guarded good-rating call. The rules list above already defines per-rating field requirements and the --missing-content section documents payload shapes, so the extra examples duplicated both. Follows the default-with-escape-hatch pattern and matches the mirrored firecrawl skill snippet. --- skills/firecrawl-search/SKILL.md | 27 ++++----------------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 95f4ba0100..27996f87cd 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -135,37 +135,18 @@ Search costs 2 credits. After you've actually used the results (or decided they - **Idempotent:** re-submitting for the same search id returns success but no extra refund. - **`--silent &`** is the right pattern β€” exit code 0 even on failure, so a rejected/expired call never crashes your pipeline. -Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. Call `search-feedback` only inside this guard β€” a failed guard (non-zero exit: missing file or zero results) skips feedback, while a bare assignment would leave `SEARCH_ID` empty and still fire the call. Send exactly one call per search; swap in the alternate rating that matches what actually happened: +Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. The guard below skips feedback when the file is missing or has zero results; call `search-feedback` only inside it: ```bash +# Send once per search. Default shown is --rating good; +# swap to partial|bad per the rules above. if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then - # Results were useful, with notes on what was still missing firecrawl search-feedback "$SEARCH_ID" \ --rating good \ --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \ - --missing-content '[ - {"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}, - {"topic":"useTransition","description":"No coverage of useTransition for routing"} - ]' \ + --missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]' \ --query-suggestions "Boost react.dev for queries about react hooks" \ --silent & - - # Alternate β€” partially useful results: multiple missing topics, one entry per topic - # firecrawl search-feedback "$SEARCH_ID" \ - # --rating partial \ - # --missing-content '[ - # {"topic":"useDeferredValue"}, - # {"topic":"useTransition","description":"Need React 18+ examples"}, - # {"topic":"Server Components hooks"} - # ]' \ - # --silent & - - # Alternate β€” bad results, quick form: repeat --missing-content or use comma-separated topics - # firecrawl search-feedback "$SEARCH_ID" \ - # --rating bad \ - # --missing-content "official api reference: missing v2 endpoints" \ - # --missing-content "code examples in python" \ - # --silent & fi ``` From d3d3ff0cc30191be2ea86bdc043dec4539e66fa3 Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:29:27 -0400 Subject: [PATCH 15/16] docs(skills): use a rating placeholder so feedback examples stay unbiased A live --rating good default anchors copy-paste agents toward reporting good and skews the feedback signal. Show a placeholder that cannot run until the agent chooses, keep the rating-neutral --missing-content field as the worked example, and let the rules list govern per-rating required fields. Applied to both mirrored snippets. --- skills/firecrawl-search/SKILL.md | 9 ++++----- skills/firecrawl/SKILL.md | 6 +++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index 27996f87cd..e19f388882 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -138,14 +138,13 @@ Search costs 2 credits. After you've actually used the results (or decided they Verify the search returned results before reading its `id`. Zero-result searches write no output file, so the file may be missing β€” or left over from an earlier search. The guard below skips feedback when the file is missing or has zero results; call `search-feedback` only inside it: ```bash -# Send once per search. Default shown is --rating good; -# swap to partial|bad per the rules above. +# Send once per search. Rate honestly and replace the placeholder with the +# rating that matches what actually happened; each rating's required +# fields are in the rules above. if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then firecrawl search-feedback "$SEARCH_ID" \ - --rating good \ - --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \ + --rating "" \ --missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]' \ - --query-suggestions "Boost react.dev for queries about react hooks" \ --silent & fi ``` diff --git a/skills/firecrawl/SKILL.md b/skills/firecrawl/SKILL.md index c26d2ab4db..f1ecd1464f 100644 --- a/skills/firecrawl/SKILL.md +++ b/skills/firecrawl/SKILL.md @@ -271,12 +271,12 @@ Search costs 2 credits per call. **After you finish using a search result**, sen ```bash # Guard: zero-result searches write no output file, so verify before reading the id. # A failed guard (missing file or zero results) skips the feedback call entirely. +# Rate honestly β€” replace the placeholder with the rating that matches +# what actually happened: good | partial | bad. if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then firecrawl search-feedback "$SEARCH_ID" \ - --rating good \ - --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Authoritative"}]' \ + --rating "" \ --missing-content '[{"topic":"useDeferredValue example"},{"topic":"Server Components hooks"}]' \ - --query-suggestions "Boost react.dev for react-hooks queries" \ --silent & fi ``` From bb03b0a4462fff06432045fa1bd3d7a36585331c Mon Sep 17 00:00:00 2001 From: Chenxin Yan Date: Tue, 18 Aug 2026 15:37:25 -0400 Subject: [PATCH 16/16] docs(skills): make the feedback example valid for every rating The collapsed example only sent --missing-content, so substituting --rating good violated the valuable-sources requirement and the --silent call swallowed the HTTP 400, silently losing the refund. Show both --valuable-sources and --missing-content so any rating substitution satisfies the substantive-content rule. --- skills/firecrawl-search/SKILL.md | 5 +++-- skills/firecrawl/SKILL.md | 4 +++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/skills/firecrawl-search/SKILL.md b/skills/firecrawl-search/SKILL.md index e19f388882..584c3d8684 100644 --- a/skills/firecrawl-search/SKILL.md +++ b/skills/firecrawl-search/SKILL.md @@ -139,11 +139,12 @@ Verify the search returned results before reading its `id`. Zero-result searches ```bash # Send once per search. Rate honestly and replace the placeholder with the -# rating that matches what actually happened; each rating's required -# fields are in the rules above. +# rating that matches what actually happened. The two fields shown +# satisfy the substantive-content rule for every rating. if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then firecrawl search-feedback "$SEARCH_ID" \ --rating "" \ + --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \ --missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]' \ --silent & fi diff --git a/skills/firecrawl/SKILL.md b/skills/firecrawl/SKILL.md index f1ecd1464f..db89fb0200 100644 --- a/skills/firecrawl/SKILL.md +++ b/skills/firecrawl/SKILL.md @@ -272,10 +272,12 @@ Search costs 2 credits per call. **After you finish using a search result**, sen # Guard: zero-result searches write no output file, so verify before reading the id. # A failed guard (missing file or zero results) skips the feedback call entirely. # Rate honestly β€” replace the placeholder with the rating that matches -# what actually happened: good | partial | bad. +# what actually happened: good | partial | bad. The two fields shown +# satisfy the substantive-content rule for every rating. if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then firecrawl search-feedback "$SEARCH_ID" \ --rating "" \ + --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Authoritative"}]' \ --missing-content '[{"topic":"useDeferredValue example"},{"topic":"Server Components hooks"}]' \ --silent & fi