headless-intelligent-search — Claude Code skill for VTEX search
Build VTEX Intelligent Search into a headless storefront, with facets, autocomplete and search analytics. Useful when a custom frontend needs product discovery.
npx skills add vtex/skills --skill headless-intelligent-search -a claude-codeWhat headless-intelligent-search does
This skill covers VTEX Intelligent Search features for product queries, facets, autocomplete, spelling corrections, popular terms and search banners. It also explains how to report search impressions and product clicks through analytics events.
Search requests can go straight from the frontend: the API is public and needs no authentication. Use API parameters for filtering and sorting rather than changing results in the client. Requests need page and locale; later pages should reuse the operator and fuzzy values returned with the first response. Search ranking degrades over time without analytics events, so event collection belongs in the search implementation.
The guidance is for headless VTEX storefronts. A BFF proxy is an option for server-side rendering, but it adds latency to a frequent operation.
What it helps with
- connect product search to a headless VTEX storefront
- add suggestions to a search field
- filter results with facets
- keep search parameters consistent across pages
- send impression and product-click events
Example prompts for the agent
- Integrate VTEX Intelligent Search into my headless storefront and add facet filters.
- Add autocomplete to the search field and report search analytics events.
- Check whether pagination reuses
operatorandfuzzyfrom the first response.
How to install headless-intelligent-search
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-intelligent-search -a claude-code2Manually: put the files in place
~/.claude/skills/headless-intelligent-search/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/headless-intelligent-search/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-intelligent-search -a codex2Manually: put the files in place
.agents/skills/headless-intelligent-search/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-intelligent-search -a cursor2Manually: put the files in place
.cursor/skills/headless-intelligent-search/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills headless-intelligent-search2Manually: put the files in place
.github/skills/headless-intelligent-search/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-intelligent-search -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/headless-intelligent-searchManually: put the files in place
.devin/skills/headless-intelligent-search/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-intelligent-search -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about headless-intelligent-search
How do I install headless-intelligent-search in Claude Code?
Run npx skills add vtex/skills --skill headless-intelligent-search -a claude-code. The skill file is at ~/.claude/skills/headless-intelligent-search/SKILL.md.
What does headless-intelligent-search do?
It guides integration of VTEX Intelligent Search with a headless storefront, including product search, facets, autocomplete and analytics events.
Which values should search pagination carry forward?
Use the operator and fuzzy values returned by the first response on subsequent pages. The API selects them based on the query.
