docs(skills): fix command examples that fail or mislead

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

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",

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 "<url>" --wait -o .firecrawl/features.json
+firecrawl agent "get feature list" --urls "<url>" --wait --json -o .firecrawl/features.json
 ```
 
 ## 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                       |
+| `--wait`               | Wait for agent to complete                            |
+| `--json`               | Output as JSON                                        |
+| `--pretty`             | Pretty print JSON (`--wait` results require `--json`) |
+| `-o, --output <path>`  | Output file path                                      |
 
 ## Tips
 

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               |
 

skills/firecrawl-download/SKILL.md

@@ -9,9 +9,9 @@ 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.
+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
 
@@ -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" -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 \

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 <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             |
+| `--node`              | Execute code as Node.js/Playwright (default)      |
+| `--python`            | Execute code as Python/Playwright                 |
+| `--bash`              | Execute code as Bash                              |
 | `--timeout <seconds>` | Execution timeout (default: 30, max: 300)         |
 | `--scrape-id <id>`    | Target a specific scrape (default: last scrape)   |
 | `-o, --output <path>` | Output file path                                  |

skills/firecrawl-scrape/SKILL.md

@@ -45,7 +45,7 @@ firecrawl scrape "https://example.com/pricing" --query "What is the enterprise p
 | ------------------------ | ---------------------------------------------------------------- |
 | `-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                                   |
+| `-H, --html`             | 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                                     |