# headless-intelligent-search

Build VTEX Intelligent Search into a headless storefront, with facets, autocomplete and search analytics. Useful when a custom frontend needs product discovery.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1100 installs · ★ 46
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/headless-intelligent-search/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/headless-intelligent-search

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-intelligent-search -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/headless-intelligent-search/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/headless-intelligent-search/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-intelligent-search -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/headless-intelligent-search/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-intelligent-search -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/headless-intelligent-search/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills headless-intelligent-search
```

2. **Manually: put the files in place**
- File: `.github/skills/headless-intelligent-search/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-intelligent-search -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/headless-intelligent-search
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/headless-intelligent-search/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-intelligent-search -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/headless-intelligent-search/SKILL.md

## When to use it
- 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
- 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 `operator` and `fuzzy` from the first response.

## Similar
- [frontend-design](https://affpapa.org/en/nevibecode/skills/frontend-design.md) — skill · 1025790 installs
- [design-taste-frontend](https://affpapa.org/en/nevibecode/skills/design-taste-frontend.md) — skill · 678700 installs
- [prototype](https://affpapa.org/en/nevibecode/skills/prototype.md) — skill · 986201 installs
- [hyperframes](https://affpapa.org/en/nevibecode/skills/heygen-com-hyperframes.md) — skill · 1200000 installs
- [hyperframes-cli](https://affpapa.org/en/nevibecode/skills/heygen-com-hyperframes-cli.md) — skill · 1300000 installs
- [webapp-testing](https://affpapa.org/en/nevibecode/skills/webapp-testing.md) — skill · 186758 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 38 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md