Agent skill · data analytics · jeremylongshore
firecrawl-advanced-troubleshooting
Isolate difficult Firecrawl v2 failures by separating caller, authentication, request, queue, rendering, origin, and result-processing evidence. Use when routine fixes fail or results are empty, partial, slow, or inconsistent. Trigger with "debug Firecrawl deeply", "empty Firecrawl result", or "stuck Firecrawl job".
Why this skill is useful
Provides systematic debugging techniques and specific code examples for troubleshooting Firecrawl issues that the AI wouldn't reliably generate on its own.
What it needs
Requires bash installed locally. Requires firecrawl account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Firecrawl Layered Troubleshooting Overview Diagnose a failing integration without leaking API keys or scraped content. Change one variable at a time and distinguish Firecrawl transport failures from target-site behavior and downstream parsing defects. Prerequisites The target repository or integration path and the requested operator outcome. The source authorization, data classification, and environment policy. Current Firecrawl documentation, credentials only when needed, and an owner for approvals. Current Contract Treat the v2 endpoint reference and the installed SDK types as the contract. SDK calls return the data object directly, REST errors normally return success false plus an error string, and completed crawl or batch results may require pagination. Use metadata.statusCode to distinguish a captured origin error page from a Firecrawl request failure. Authentication For authenticated Cloud operations, inject FIRECRAWLAPIKEY from an approved secret manager. REST requests use Authorization: Bearer with the key. Never print, commit, transmit, or place a key in a URL. Keyless access is suitable only where the current documentation explicitly allows it and the workload accepts its limits; production workflows should make identity and team ownership explicit. Instructions 1. Record the client package, resolved version, runtime, endpoint family, request class, opaque request or job ID, and first failing timestamp. Redact URLs when their paths or queries are sensitive. 2. Reproduce with one approved public or synthetic URL and the smallest output format. If that succeeds, the credential and base route are probably sound; do not infer that the target is healthy. 3. Compare the failing request with the current v2 schema. Remove optional actions, headers, proxy choices, JSON extraction, and cache overrides one at a time. 4. For async work, inspect queue status, job state, pagination cursor, crawl errors, and terminal status. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/firecrawl-advanced-troubleshooting