Skip to content

docs(skills): fix behavior claims that don't match the CLI #191

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
chenxin-yan wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(skills): fix behavior claims that don't match the CLI #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f53a53a
docs(skills): correct behavior claims
chenxin-yan Aug 17, 2026
43872be
docs(skills): clarify multi-URL scrape drops non-markdown formats
chenxin-yan Aug 17, 2026
30fe1a2
docs(skills): fix remaining wrong claims found in review
chenxin-yan Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 30 additions & 11 deletions skills/firecrawl-agent/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,22 +30,41 @@ firecrawl agent "extract products" --schema '{"type":"object","properties":{"nam
firecrawl agent "get feature list" --urls "<url>" --wait -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 "<job-id>"

# Wait on an existing job, polling every 10 seconds for up to 5 minutes
firecrawl agent "<job-id>" --wait --poll-interval 10 --timeout 300

# Cancel an active job
firecrawl agent "<job-id>" --cancel
```

## Options

| Option | Description |
| ---------------------- | ----------------------------------------- |
| `--urls <urls>` | Starting URLs for the agent |
| `--model <model>` | Model to use: spark-1-mini or spark-1-pro |
| `--schema <json>` | JSON schema for structured output |
| `--schema-file <path>` | Path to JSON schema file |
| `--max-credits <n>` | Credit limit for this agent run |
| `--wait` | Wait for agent to complete |
| `--pretty` | Pretty print JSON output |
| `-o, --output <path>` | Output file path |
| Option | Description |
| --------------------------- | --------------------------------------------------- |
| `--urls <urls>` | Starting URLs for the agent |
| `--model <model>` | Model to use: spark-1-mini or spark-1-pro |
| `--schema <json>` | JSON schema for structured output |
| `--schema-file <path>` | Path to JSON schema file |
| `--max-credits <n>` | 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 <seconds>` | Polling interval while waiting (default: 5 seconds) |
| `--timeout <seconds>` | Stop waiting after this duration (default: none) |
| `--pretty` | Pretty print JSON output |
| `-o, --output <path>` | Output file path |

## 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.
Expand Down
7 changes: 3 additions & 4 deletions skills/firecrawl-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */]
}
}
}
Expand Down Expand Up @@ -269,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 \
Expand Down
24 changes: 13 additions & 11 deletions skills/firecrawl-download/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ allowed-tools:
- Bash(npx firecrawl *)
---

# firecrawl download
# firecrawl download (invoked as `firecrawl x download`)

> **Experimental.** Convenience command that combines `map` + `scrape` to save an entire site as local files.

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 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. Always pass `-y` to skip the confirmation prompt.

## When to use

Expand All @@ -22,24 +22,24 @@ Maps the site first to discover pages, then scrapes each one into nested directo
## Quick start

```bash
# Interactive wizard (picks format, screenshots, paths for you)
firecrawl download https://docs.example.com
# 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
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" -y

# 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" -y

# 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 \
Expand All @@ -58,9 +58,11 @@ firecrawl 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

`-f <formats>`, `-H`, `-S`, `--screenshot`, `--full-page-screenshot`, `--only-main-content`, `--include-tags`, `--exclude-tags`, `--wait-for`, `--max-age`, `--country`, `--languages`
Only the options listed below are supported:

`-f <formats>`, `-H`, `-S`, `--lockdown`, `--screenshot`, `--full-page-screenshot`, `--only-main-content`, `--include-tags`, `--exclude-tags`, `--wait-for`, `--max-age`, `--country`, `--languages`

## See also

Expand Down
33 changes: 18 additions & 15 deletions skills/firecrawl-interact/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,29 +25,32 @@ 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 "<url>"

# 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 "<scrape-id>" "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 "click @e5" --bash
firecrawl interact --code "snapshot -i" --bash

# 4. Stop the session when done
firecrawl interact stop
```

## Options

| Option | Description |
| --------------------- | ------------------------------------------------- |
| `--prompt <text>` | Natural language instruction (use this OR --code) |
| `--code <code>` | Code to execute in the browser session |
| `--language <lang>` | Language for code: bash, python, node |
| `--timeout <seconds>` | Execution timeout (default: 30, max: 300) |
| `--scrape-id <id>` | Target a specific scrape (default: last scrape) |
| `-o, --output <path>` | Output file path |
| Option | Description |
| -------------------------------- | ------------------------------------------------- |
| `--prompt <text>` | Natural language instruction (use this OR --code) |
| `--code <code>` | Code to execute in the browser session |
| `--node` / `--python` / `--bash` | Language for `--code` (default: node) |
| `--timeout <seconds>` | Execution timeout (default: 30, max: 300) |
| `--scrape-id <id>` | Target a specific scrape (default: last scrape) |
| `-o, --output <path>` | Output file path |

## Profiles

Expand All @@ -72,7 +75,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`

Expand Down
18 changes: 9 additions & 9 deletions skills/firecrawl-parse/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 <prompt>` | Ask a question about the parsed content |
| `-o, --output <path>` | Output file path — **always use this** |
| `-f, --format <fmt>` | `markdown` (default), `html`, `summary` |
| `--timeout <ms>` | Timeout for the parse job |
| `--timing` | Show request duration |
| Option | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `-S, --summary` | AI-generated summary |
| `-Q, --query <prompt>` | Ask a question about the parsed content |
| `-o, --output <path>` | Output file path — **always use this** |
| `-f, --format <formats>` | Comma-separated: `markdown`, `html`, `rawHtml`, `links`, `images`, `summary`, `json`, `attributes`. Multiple formats output JSON |

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The -f/--format list is incomplete: it omits screenshot, changeTracking, and branding. Parse's --format is parsed by the shared parseFormats in src/utils/options.ts, which accepts all 11 VALID_FORMATS (markdown, html, rawHtml, links, images, screenshot, summary, changeTracking, json, attributes, branding) and rejects nothing at parse time. The doc reads as an exhaustive list, so an agent will believe those three values are invalid and the accuracy goal of this PR is not fully met. Either add the missing values or state that only these 8 are meaningful for parse.

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

<comment>The `-f/--format` list is incomplete: it omits `screenshot`, `changeTracking`, and `branding`. Parse's `--format` is parsed by the shared `parseFormats` in `src/utils/options.ts`, which accepts all 11 `VALID_FORMATS` (markdown, html, rawHtml, links, images, screenshot, summary, changeTracking, json, attributes, branding) and rejects nothing at parse time. The doc reads as an exhaustive list, so an agent will believe those three values are invalid and the accuracy goal of this PR is not fully met. Either add the missing values or state that only these 8 are meaningful for parse.</comment>

<file context>
@@ -39,14 +39,14 @@ Then `head`, `grep`, `rg` etc., or incrementally read the file - don't load the
+| `-S, --summary`          | AI-generated summary                                                                                                             |
+| `-Q, --query <prompt>`   | Ask a question about the parsed content                                                                                          |
+| `-o, --output <path>`    | Output file path — **always use this**                                                                                           |
+| `-f, --format <formats>` | Comma-separated: `markdown`, `html`, `rawHtml`, `links`, `images`, `summary`, `json`, `attributes`. Multiple formats output JSON |
+| `--timeout <ms>`         | Timeout for the parse job                                                                                                        |
+| `--timing`               | Show request duration                                                                                                            |
</file context>
Fix with cubic

| `--timeout <ms>` | Timeout for the parse job |
| `--timing` | Show request duration |

## Tips

Expand Down
26 changes: 13 additions & 13 deletions skills/firecrawl-scrape/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ firecrawl scrape "<url>" --only-main-content -o .firecrawl/page.md
# Wait for JS to render, then scrape
firecrawl scrape "<url>" --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
Expand All @@ -41,23 +41,23 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p

## Options

| Option | Description |
| ------------------------ | ---------------------------------------------------------------- |
| `-f, --format <formats>` | Output formats: markdown, html, rawHtml, links, screenshot, json |
| `-Q, --query <prompt>` | Ask a question about the page content (5 credits) |
| `-H` | Include HTTP headers in output |
| `--only-main-content` | Strip nav, footer, sidebar — main content only |
| `--wait-for <ms>` | Wait for JS rendering before scraping |
| `--include-tags <tags>` | Only include these HTML tags |
| `--exclude-tags <tags>` | Exclude these HTML tags |
| `--redact-pii` | Redact personally identifiable information from output |
| `-o, --output <path>` | Output file path |
| Option | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `-f, --format <formats>` | Output formats: markdown, html, rawHtml, links, images, screenshot, summary, changeTracking, json, attributes, branding |
| `-Q, --query <prompt>` | Ask a question about the page content (5 credits) |
| `-H` | Output raw HTML (shortcut for `--format html`) |
| `--only-main-content` | Strip nav, footer, sidebar — main content only |
| `--wait-for <ms>` | Wait for JS rendering before scraping |
| `--include-tags <tags>` | Only include these HTML tags |
| `--exclude-tags <tags>` | Exclude these HTML tags |
| `--redact-pii` | Redact personally identifiable information from output |
| `-o, --output <path>` | 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 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`
Expand Down
6 changes: 3 additions & 3 deletions skills/firecrawl-search/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Read the search response's `id`:
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 -r '.id' .firecrawl/search-react-hooks.json)
SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json)

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The guard only detects a missing/empty result file; it cannot detect a stale file left over from an earlier search. The same fixed path (search-react-hooks.json) is reused, so a zero-result search that writes nothing leaves the previous successful file, whose data arrays are non-empty and pass any(.data[]; length > 0). The agent would then send feedback with the old id, contradicting the guard's stated protection ("may be left over from an earlier search. Only send feedback when this guard succeeds"). Consider using a per-query path (the doc's own naming convention is search-{query}.json) or noting explicitly that the guard does not detect staleness.

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

<comment>The guard only detects a missing/empty result file; it cannot detect a stale file left over from an earlier search. The same fixed path (`search-react-hooks.json`) is reused, so a zero-result search that writes nothing leaves the previous successful file, whose `data` arrays are non-empty and pass `any(.data[]; length > 0)`. The agent would then send feedback with the old id, contradicting the guard's stated protection ("may be left over from an earlier search. Only send feedback when this guard succeeds"). Consider using a per-query path (the doc's own naming convention is `search-{query}.json`) or noting explicitly that the guard does not detect staleness.</comment>

<file context>
@@ -135,13 +135,13 @@ Search costs 2 credits. After you've actually used the results (or decided they
 
 ```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)

</file context>


</details>

<a href="https://www.cubic.dev/action/fix/violation/f9db8d38-4b32-4628-9050-5e0141f165ae" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://cubic.dev/buttons/fix-with-cubic-light.svg">
    <img alt="Fix with cubic" src="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
  </picture>
</a>

```

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
Expand Down
Loading