---
name: algolia-migration-deep-dive
description: >-
  Plan and execute a reversible migration from another search system or legacy index design to Algolia. Use when translating schemas, queries, relevance behavior, or production traffic. Trigger with "migrate to Algolia", "Algolia cutover", or "search engine migration".
argument-hint: "[repository-path] [source-system] [target-index]"
allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit
version: 1.8.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags:
  - saas
  - algolia
  - migration
model: inherit
effort: medium
compatibility: Designed for Claude Code
title: algolia-migration-deep-dive
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/algolia-migration-deep-dive
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/official-docs.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/algolia-migration-deep-dive/references/official-docs.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/algolia-migration-deep-dive`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/algolia-migration-deep-dive`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/algolia-migration-deep-dive) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/algolia-migration-deep-dive`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/algolia-migration-deep-dive --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/algolia-migration-deep-dive --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Algolia Search Migration

## Overview

This skill treats migration as a measured compatibility program: source data, query semantics, ranking, filters, UI behavior, traffic, and rollback are assessed separately before cutover.

## Prerequisites

- A named repository, environment, and Algolia application or index in scope
- The local lockfile and installed client types as implementation authority
- A safe read-only query or explicitly disposable test target
- Current first-party documentation for any provider behavior that affects the change

## Tool Discipline

Use `Read`, `Glob`, and `Grep` to inspect local code, configuration names, tests, and dependency versions. Use `WebFetch` only for current official Algolia documentation. Use `Write` or `Edit` only after identifying the target files, constraints, and verification plan.

## Current Contract

- Preserve the source system as the rollback authority until acceptance criteria pass.
- Translate capabilities from observed queries and product journeys, not feature-name similarity.
- Build a new target index and avoid in-place destructive conversion.
- Compare relevance with a representative, owner-approved query set and explicit tolerances.

## Authentication

Use separate least-privilege credentials for source reads, Algolia writes, and browser search. Keep all secret material outside migration artifacts.

## Instructions

1. Inventory source schema, analyzers, queries, filters, facets, ranking behavior, traffic, and operational constraints.
2. Define the Algolia record model, stable IDs, settings, synonyms, rules, and unsupported semantic gaps.
3. Backfill a new target index from a reproducible source snapshot and retain task receipts.
4. Run structural checks, representative query comparisons, latency observations, and UI acceptance tests.
5. Shadow or canary traffic when available, with named rollback thresholds and owners.
6. Cut over only after approval, then reconcile drift and retain the rollback window.

## Approval Boundaries

Do not overwrite the current production index, declare relevance equivalence from a few queries, or retire the source system before rollback expiry.

## Output

Return the capability map, data transform, gap register, backfill evidence, query comparison, cutover plan, acceptance decision, and rollback procedure.

## Error Handling

| Condition | Response |
|---|---|
| Unsupported query feature | Document the gap and design an approved product alternative. |
| Record counts differ | Reconcile filtering, deletes, and source snapshot boundaries. |
| Relevance regresses | Keep source traffic and tune against the approved query set. |
| Rollback data drifts | Define dual-write or replay before cutover. |

## Examples

Use this compact input and expected handoff to calibrate scope and evidence quality.

Input:

```text
source=legacy-search; snapshot=snap-184; target=products_algolia_next
```

Expected handoff:

```text
records=reconciled; query-suite=198/200; two-gaps=owner-review; cutover=not-started
```

## Resources

- [Skill-specific official documentation](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/algolia-migration-deep-dive/references/official-docs.md)
- [Sending and managing data](https://www.algolia.com/doc/guides/sending-and-managing-data)
- [Relevance](https://www.algolia.com/doc/guides/managing-results)
- [API keys](https://www.algolia.com/doc/guides/security/api-keys)
