xcrawl-search
starsforks
How to install xcrawl-search?
xcrawl-api/xcrawl-skills/xcrawl-search
$npx -y skills add xcrawl-api/xcrawl-skills --skill xcrawl-searchUse this skill for XCrawl search tasks, including keyword search request design, location and language controls, result analysis, and follow-up crawl or scrape planning.
SKILL.md
| 1 | # XCrawl Search |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | This skill uses XCrawl Search API to retrieve query-based results. |
| 6 | Default behavior is raw passthrough: return upstream API response bodies as-is. |
| 7 | |
| 8 | ## Required Local Config |
| 9 | |
| 10 | Before using this skill, the user must create a local config file and write `XCRAWL_API_KEY` into it. |
| 11 | |
| 12 | Path: `~/.xcrawl/config.json` |
| 13 | |
| 14 | ```json |
| 15 | { |
| 16 | "XCRAWL_API_KEY": "<your_api_key>" |
| 17 | } |
| 18 | ``` |
| 19 | |
| 20 | Read API key from local config file only. Do not require global environment variables. |
| 21 | |
| 22 | ## Credits and Account Setup |
| 23 | |
| 24 | Using XCrawl APIs consumes credits. |
| 25 | If the user does not have an account or available credits, guide them to register at `https://dash.xcrawl.com/`. |
| 26 | After registration, they can activate the free `1000` credits plan before running requests. |
| 27 | |
| 28 | ## Tool Permission Policy |
| 29 | |
| 30 | Request runtime permissions for `curl` and `node` only. |
| 31 | Do not request Python, shell helper scripts, or other runtime permissions. |
| 32 | |
| 33 | ## API Surface |
| 34 | |
| 35 | - Search endpoint: `POST /v1/search` |
| 36 | - Base URL: `https://run.xcrawl.com` |
| 37 | - Required header: `Authorization: Bearer <XCRAWL_API_KEY>` |
| 38 | |
| 39 | ## Usage Examples |
| 40 | |
| 41 | ### cURL |
| 42 | |
| 43 | ```bash |
| 44 | API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")" |
| 45 | |
| 46 | curl -sS -X POST "https://run.xcrawl.com/v1/search" \ |
| 47 | -H "Content-Type: application/json" \ |
| 48 | -H "Authorization: Bearer ${API_KEY}" \ |
| 49 | -d '{"query":"AI web crawler API","location":"US","language":"en","limit":20}' |
| 50 | ``` |
| 51 | |
| 52 | ### Node |
| 53 | |
| 54 | ```bash |
| 55 | node -e ' |
| 56 | const fs=require("fs"); |
| 57 | const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+"/.xcrawl/config.json","utf8")).XCRAWL_API_KEY; |
| 58 | const body={query:"web scraping pricing",location:"DE",language:"de",limit:30}; |
| 59 | fetch("https://run.xcrawl.com/v1/search",{ |
| 60 | method:"POST", |
| 61 | headers:{"Content-Type":"application/json",Authorization:`Bearer ${apiKey}`}, |
| 62 | body:JSON.stringify(body) |
| 63 | }).then(async r=>{console.log(await r.text());}); |
| 64 | ' |
| 65 | ``` |
| 66 | |
| 67 | ## Request Parameters |
| 68 | |
| 69 | ### Request endpoint and headers |
| 70 | |
| 71 | - Endpoint: `POST https://run.xcrawl.com/v1/search` |
| 72 | - Headers: |
| 73 | - `Content-Type: application/json` |
| 74 | - `Authorization: Bearer <api_key>` |
| 75 | |
| 76 | ### Request body: top-level fields |
| 77 | |
| 78 | | Field | Type | Required | Default | Description | |
| 79 | |---|---|---:|---|---| |
| 80 | | `query` | string | Yes | - | Search query | |
| 81 | | `location` | string | No | `US` | Location (country/city/region name or ISO code; best effort) | |
| 82 | | `language` | string | No | `en` | Language (ISO 639-1) | |
| 83 | | `limit` | integer | No | `10` | Max results (`1-100`) | |
| 84 | |
| 85 | ## Response Parameters |
| 86 | |
| 87 | | Field | Type | Description | |
| 88 | |---|---|---| |
| 89 | | `search_id` | string | Task ID | |
| 90 | | `endpoint` | string | Always `search` | |
| 91 | | `version` | string | Version | |
| 92 | | `status` | string | `completed` | |
| 93 | | `query` | string | Search query | |
| 94 | | `data` | object | Search result data | |
| 95 | | `started_at` | string | Start time (ISO 8601) | |
| 96 | | `ended_at` | string | End time (ISO 8601) | |
| 97 | | `total_credits_used` | integer | Total credits used | |
| 98 | |
| 99 | `data` notes from current API reference: |
| 100 | |
| 101 | - Concrete result schema is implementation-defined |
| 102 | - Includes billing fields like `credits_used` and `credits_detail` |
| 103 | |
| 104 | ## Workflow |
| 105 | |
| 106 | 1. Rewrite the request as a clear search objective. |
| 107 | - Include entity, geography, language, and freshness intent. |
| 108 | |
| 109 | 2. Build and execute `POST /v1/search`. |
| 110 | - Keep request explicit and deterministic. |
| 111 | |
| 112 | 3. Return raw API response directly. |
| 113 | - Do not synthesize relevance summaries unless requested. |
| 114 | |
| 115 | ## Output Contract |
| 116 | |
| 117 | Return: |
| 118 | |
| 119 | - Endpoint used (`POST /v1/search`) |
| 120 | - `request_payload` used for the request |
| 121 | - Raw response body from search call |
| 122 | - Error details when request fails |
| 123 | |
| 124 | Do not generate summaries unless the user explicitly requests a summary. |
| 125 | |
| 126 | ## Guardrails |
| 127 | |
| 128 | - Do not claim ranking guarantees that the API does not expose. |
| 129 | - Do not fabricate unavailable filters or response fields. |
| 130 | - Do not hardcode provider-specific tool schemas in core logic. |
People who liked this also viewed
6 picksType
- azure-aiUse for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector searSkillsJul 2026
- just-scrapeSearch, scrape, crawl, extract structured data, and monitor web pages via the ScrapeGraph AI CLI. Use when the user asks to search the web, scrape a webpage, grab content from a URL, extract JSON fromSkillsJul 2026
- firecrawlCLI and Agent Skill for Firecrawl - Add scrape, search, and browsing capabilities to your AI agentsSkillsJul 2026
- firecrawl-searchWeb search with full page content extraction. 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 "SkillsJul 2026
- firecrawl-agentAI-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, producSkillsJul 2026
- firecrawl-mapDiscover 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 sSkillsJul 2026
