firecrawl-advanced-troubleshooting
Debug hard-to-diagnose Firecrawl issues with systematic isolation and evidence collection. Use when standard troubleshooting fails, investigating why scrapes return empty content, crawl jobs hang, or webhooks don't fire. Trigger with phrases like "firecrawl hard bug", "firecrawl mystery error", "firecrawl impossible to debug", "firecrawl deep debug", "firecrawl not scraping".
71
88%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that clearly defines its scope, provides explicit trigger guidance, and distinguishes itself from general Firecrawl troubleshooting. It uses third person voice correctly, lists concrete problem scenarios, and includes both 'Use when' and 'Trigger with' clauses for maximum discoverability.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and scenarios: 'systematic isolation and evidence collection', 'scrapes return empty content', 'crawl jobs hang', 'webhooks don't fire'. These are concrete, actionable problem types. | 3 / 3 |
Completeness | Clearly answers both 'what' (debug hard-to-diagnose Firecrawl issues with systematic isolation and evidence collection) and 'when' (when standard troubleshooting fails, with specific scenarios and explicit trigger phrases). Has both a 'Use when' clause and a 'Trigger with' clause. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including both user-friendly phrases ('firecrawl hard bug', 'firecrawl mystery error', 'firecrawl not scraping') and technical scenarios ('empty content', 'crawl jobs hang', 'webhooks don't fire'). The explicit 'Trigger with phrases like...' clause is very helpful. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — targets a specific tool (Firecrawl) and a specific niche within that tool (hard-to-diagnose issues vs. standard troubleshooting). The explicit differentiation from 'standard troubleshooting' helps distinguish it from a general Firecrawl skill. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable troubleshooting skill with executable diagnostic code and a clear systematic workflow. Its main weakness is length — the detailed TypeScript functions could be split into a companion file to keep SKILL.md as a concise overview. There's also some redundancy between the minimal reproduction and layer-by-layer isolation steps.
Suggestions
Extract the detailed diagnostic functions (Steps 2-5) into a companion file like DIAGNOSTICS.md or a TypeScript utility file, keeping SKILL.md as a concise overview with the error table and escalation template.
Consolidate Steps 1 and 2, which both test API connectivity and target URL accessibility, to eliminate redundancy.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with executable code examples, but there's some redundancy between Step 1 (Minimal Reproduction) and Step 2 (Layer-by-Layer Isolation) which both test API connectivity and target URL scraping. Some inline comments are unnecessary for Claude (e.g., explaining what a screenshot shows). The error handling table and escalation template are lean and useful. | 2 / 3 |
Actionability | Every step provides fully executable TypeScript code with specific Firecrawl API calls, concrete diagnostic checks (regex patterns for error detection, content length thresholds), and clear diagnostic output. The error handling table maps specific symptoms to causes and solutions. The escalation template is copy-paste ready. | 3 / 3 |
Workflow Clarity | The 5-step workflow follows a clear logical progression: minimal reproduction → layer-by-layer isolation → specific issue debugging (empty scrapes, stuck crawls) → timing analysis. Each step has explicit pass/fail criteria and diagnostic output. The layer-by-layer isolation includes an early-return pattern (can't continue if API connectivity fails), which serves as a validation checkpoint. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections, but it's quite long (~200 lines of code) and could benefit from splitting detailed diagnostic functions into a separate reference file. The 'Next Steps' reference to `firecrawl-load-scale` is good, and external resource links are provided, but the main body is monolithic for a SKILL.md. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
a04d1a2
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.