> ## 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

> Write natural-language merchandising rules that Layers attaches to every AI step in the search pipeline, from query expansion to result evaluation.

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

## 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 [request transform](/platform/request-transforms) 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](/platform/merchandising), [pins](/platform/merchandising/pins), or [request transforms](/platform/request-transforms) for product-level control.

### Example

```text theme={null}
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](/help/configuration/configure-search-instructions).

## Interactions with other features

* **[Request transforms](/platform/request-transforms)** 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](/platform/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](/platform/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](/platform/autocomplete-curation)** has its own brand prompt for the typeahead experience. Search instructions affect search, not autocomplete.

## See also

* [Configure search instructions](/help/configuration/configure-search-instructions) — Step-by-step dashboard walkthrough
* [Request transforms](/platform/request-transforms) — Request-time query and filter modifications
* [Ranking relevancy](/platform/ranking-relevancy) — Signal weights and ranking rules
* [Semantic redirects](/platform/semantic-redirects) — Route specific search queries to landing pages