Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

Search instructions are currently in beta. The dashboard page is marked with a Beta badge. Behavior may change before general availability.

​
Overview

Search instructions are a single, store-wide block of merchandising guidance written in plain English. Layers attaches the same instructions to every AI step in the search pipeline. A rule like “promote bestsellers, demote items in their first 30 days” propagates everywhere the pipeline makes a judgement call — without you having to configure each step separately. You write the instructions once on the Search Instructions settings page. Layers wraps them in a dedicated block in the system prompt of every AI step and re-uses the same block across the pipeline.

​
When to use it

Use search instructions when you want one consistent piece of merchandising guidance to influence multiple parts of the search experience at once. Common scenarios:
  • Cross-pipeline merchandising guidance. Promote a category, demote certain product types, or favor specific brands across every AI-driven decision in search.
  • Seasonal direction. Tell the pipeline to favor seasonal collections, holiday-relevant items, or current campaigns whenever a query is generic enough to allow it.
  • Lifecycle rules. Demote brand-new products until they have engagement data, or de-prioritize end-of-life inventory the same way across every AI step.
  • Brand voice and taste. Communicate editorial preferences (“prefer premium variants when the query is ambiguous”) that you don’t want to encode in a query-by-query rule.
If you only need to change one step — for example, expand a specific query a particular way — a search rule or per-pipeline configuration is usually a better fit. Search instructions are designed for guidance that should apply everywhere in the AI search pipeline.

​
How it works

The instructions you save are attached to the system prompt of each AI step in the search pipeline. The pipeline steps that receive your instructions are:
  • Query expansion — generating related terms and synonyms for a shopper’s query.
  • Intent detection — interpreting what a shopper is looking for and modifying the request accordingly.
  • Facet value ordering — deciding which facet values to surface and in what order.
  • Semantic redirect approval — judging whether a suggested redirect should fire for a query.
  • Search result evaluation — judging the quality of a result set for relevance and merchandising fit.
Other parts of the search pipeline are intentionally not affected by search instructions:
  • Query interpretation (redirect and SKU detection) is about understanding the input, not ranking. It ignores merchandising guidance.
  • Embeddings and content guardrails don’t run text prompts, so there is nothing to attach instructions to.

​
Interaction with per-step instructions

Search instructions don’t replace any per-step configuration you already have. They are concatenated with it:
  • The query expansion step still respects its own per-step instructions; your search instructions are appended to them.
  • The intent detection step still respects any per-call custom instructions; your search instructions are appended to them.
  • Facet value ordering, redirect approval, and result evaluation receive your search instructions as an additional block in the system prompt.
If a per-step instruction conflicts with a search instruction, the model sees both. Keep your search instructions broad and consistent; use per-step configuration for narrower, technical guidance.

​
When changes take effect

Saving search instructions is effectively immediate:
  • Cached prompts for your store are invalidated as soon as you save, so the next search uses the new text.
  • Clearing the field removes the instructions block from every pipeline step on the next request.
You do not need to re-index your catalog or restart anything.

​
Writing good search instructions

Search instructions are free-form text up to 5,000 characters. Treat them like a short merchandising brief, not code. Good instructions are specific, rule-based, and focused on decisions only you can make:
  • “Promote items with high purchase rates and 4+ star reviews. Demote new arrivals during their first 30 days.”
  • “When the query is generic (for example, just a category name), surface the current seasonal collection first.”
  • “Treat clearance items as last-resort results. Only show them when better-margin alternatives don’t match the query.”
  • “This store is kosher-certified. Never promote products tagged with pork or shellfish, even if relevance scores are high.”
Avoid:
  • Restating what you sell — Layers already knows your catalog.
  • Trying to override technical behavior (typo handling, language detection, embedding similarity). Use the appropriate per-feature setting instead.
  • Long lists of product IDs or SKUs. Use merchandising rules, pins, or search rules for product-level control.

​
Example

Merchandising guidance:

- Promote bestsellers (high purchase rate over the last 30 days)
  when the query is generic.
- Demote items in their first 30 days on sale — they don't yet
  have enough engagement data to rank confidently.
- For ambiguous queries, prefer in-season collections over
  evergreen ones.
- Never promote clearance items above full-price equivalents
  for the same query.

​
Configuration

Configure search instructions in the Layers dashboard under Settings → Search & Discovery → Search Instructions. For step-by-step instructions, see Configure search instructions.

​
Interactions with other features

  • Search rules run at request time and modify the request itself (filters, sort orders, query rewrites). Search instructions guide the AI steps that run inside the pipeline. The two are complementary.
  • Ranking relevancy controls deterministic signal weights and ranking rules. Search instructions influence the AI judgement layered on top of ranking, not the signal weights themselves.
  • Semantic redirects still go through their own approval step, which now sees your search instructions when deciding whether a suggested redirect is appropriate.
  • Autocomplete curation has its own brand prompt for the typeahead experience. Search instructions affect search, not autocomplete.

​
See also