feat: add algolia-migration skill for API client upgrades

.claude-plugin/marketplace.json

@@ -53,6 +53,15 @@
       "skills": [
         "./skills/algolia-crawler"
       ]
+    },
+    {
+      "name": "algolia-migration",
+      "description": "Migrate existing Algolia backend/server-side API client code, or frontend search-only builds (lite client), to the latest major version. Use when upgrading algoliasearch packages, fixing initIndex removal, replacing .wait() chaining, updating imports after a version bump, or handling any breaking changes across JS (v4→v5), Python (v3→v4), Go (v3→v4), PHP (v3→v4), Java (v3→v4), C# (v6→v7), Ruby (v2→v3), Kotlin (v2→v3), Scala (v1→v2), or Swift (v8→v9). Do NOT use for new project setup, InstantSearch frontend widgets, analytics queries, or recommendations.",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/algolia-migration"
+      ]
     }
   ]
 }

README.md

@@ -19,6 +19,7 @@
 | `algobot-cli`   | AI agents, Agent Studio, RAG, and conversational experiences built on Algolia      |
 | `instantsearch` | Build search UIs (autocomplete, search results, faceted search) with InstantSearch |
 | `algolia-crawler` | Crawl web pages or whole sites into a RAG-optimized index with the Algolia Crawler |
+| `algolia-migration` | Migrate API client code to the latest major version (JS, Python, Go, PHP, Java, C#, Ruby, Kotlin, Scala, Swift) |
 
 ---
 
@@ -28,13 +29,13 @@
 
 ```bash
 /plugin marketplace add algolia/skills
-/plugin install <skill>   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler
+/plugin install <skill>   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler, algolia-migration
 ```
 
 Or install directly:
 
 ```bash
-/plugin install <skill>@algolia-skills   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler
+/plugin install <skill>@algolia-skills   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler, algolia-migration
 ```
 
 #### npx
@@ -47,7 +48,7 @@ npx skills add https://github.com/algolia/skills
 
 ```bash
 git clone https://github.com/algolia/skills.git
-cp -r skills/<skill> <skills-directory>   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler
+cp -r skills/<skill> <skills-directory>   # e.g. algolia-mcp, algolia-cli, algobot-cli, instantsearch, algolia-crawler, algolia-migration
 ```
 
 <details>

skills/algolia-migration/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: algolia-migration
+description: >-
+  Migrate existing Algolia API client code to a newer major version.
+  Triggers on: upgrading algoliasearch, moving from initIndex to client methods,
+  fixing "initIndex is not a function", updating imports after a version bump,
+  handling breaking changes from v3→v4 or v4→v5, replacing .wait() chaining,
+  or any mention of "migrate Algolia client", "upgrade Algolia SDK", or a
+  specific old-to-new version (e.g. "Python v3 to v4", "JS v4 to v5").
+  Covers JavaScript, Python, Go, PHP, Java, C#, Ruby, Kotlin, Scala, Swift. Dart is a new client and is excluded from scope.
+  Do NOT use for new project setup (use algolia-cli or algolia-mcp instead),
+  InstantSearch / frontend frameworks, analytics queries, or recommendations.
+license: MIT
+metadata:
+  author: algolia
+  version: "1.0"
+---
+
+# Algolia API Client Migration
+
+> This skill covers **API client upgrades** (backend and frontend search-only builds).
+> For frontend search UI, see **instantsearch**. For index operations, see **algolia-cli**.
+
+## Supported migrations
+
+| Language   | Migration    | Reference |
+|------------|--------------|-----------|
+| JavaScript | v4 → v5      | [references/javascript.md](references/javascript.md) |
+| Python     | v3 → v4      | [references/python.md](references/python.md) |
+| Go         | v3 → v4      | [references/go.md](references/go.md) |
+| PHP        | v3 → v4      | [references/php.md](references/php.md) |
+| Java       | v3 → v4      | [references/java.md](references/java.md) |
+| C#         | v6 → v7      | [references/csharp.md](references/csharp.md) |
+| Ruby       | v2 → v3      | [references/ruby.md](references/ruby.md) |
+| Kotlin     | v2 → v3      | [references/kotlin.md](references/kotlin.md) |
+| Scala      | v1 → v2      | [references/scala.md](references/scala.md) |
+| Swift      | v8 → v9      | [references/swift.md](references/swift.md) |
+
+Open the matching reference file before writing any migration code.
+
+## Universal breaking changes
+
+Every language migration shares the same set of architectural shifts. Understand these first; the reference files add language-specific syntax on top.
+
+### 1. `initIndex` is gone
+
+The index object pattern is eliminated in every language. All methods moved to the **client** with `indexName` as an explicit parameter.
+
+**The fix:** remove `initIndex` / `init_index` / `index(withName:)`, call the method on the client, pass `indexName`.
+
+**Grep to find all affected call sites:**
+```
+grep -r "initIndex\|init_index\|InitIndex\|index(withName" .
+```
+
+### 2. `.wait()` chaining is gone
+
+Chained `.wait()` / `!` bang methods on task responses are replaced by dedicated wait helpers.
+
+| Old | New |
+|-----|-----|
+| `index.saveObjects(records).wait()` | `client.waitForTask(...)` with the index name and task ID |
+| `index.save_objects!(objects)` (Ruby) | `client.save_objects(index_name, objects, true)` |
+
+Three helpers available in every language: `waitForTask`, `waitForAppTask`, `waitForApiKey`. The exact calling convention varies by language (e.g. JS v5 takes an options object, Python uses keyword arguments) — see the language reference for the precise signature.
+
+### 3. `copyIndex` / `moveIndex` → `operationIndex`
+
+All index copy and move operations, including scoped copies (`copyRules`, `copySettings`, `copySynonyms`), consolidate into a single `operationIndex` call with `operation: "copy"` or `"move"` and an optional `scope` array.
+
+### 4. `objectID` is required in `saveObjects`
+
+`autoGenerateObjectIDIfNotExist` is removed. Every object passed to `saveObjects` must include an explicit `objectID`. To let the API generate IDs, use `chunkedBatch` with `action: addObject`.
+
+### 5. `replaceAllObjects` — `scopes` is optional
+
+The `safe` option is removed. The `scopes` parameter defaults to `["settings", "rules", "synonyms"]` in every language — you only need to pass it explicitly if you want a subset.
+
+### 6. Browse helpers change pattern
+
+The old iterator/chained patterns are gone. The new pattern **varies by language** — check the reference file:
+
+- **Aggregator callback** (JS, Python, Go, Ruby, Scala, Swift): pass an `aggregator` function that receives each page response
+- **Iterable** (C#, Java): the helper returns an `IEnumerable<T>` / `Iterable<T>` — iterate with `foreach` or `.forEach()`
+- **Iterable / foreach** (PHP): the method returns `ObjectIterator` — iterate with a for-each loop
+
+### 7. `AccountClient` is gone
+
+Cross-application index copies now require composing helpers across two client instances manually: get settings from source, set on destination; browse + save for rules, synonyms, and objects.
+
+JavaScript exception: v5 ships `client.accountCopyIndex({ sourceIndexName, destinationAppID, destinationApiKey, destinationIndexName, ... })` as a built-in. No manual composition needed, but the call signature differs from v4's `accountCopyIndex(srcIndex, destIndex)` — see references/javascript.md.
+
+### 8. Dedicated clients per API
+
+Each API now has its own client class. If the code previously imported one monolithic client, update imports for `RecommendClient`, `AnalyticsClient`, `AbtestingClient`, etc.
+
+## Migration workflow
+
+1. **Detect language and version** from the project's package manifest (`package.json`, `go.mod`, `composer.json`, `pom.xml`, `Gemfile`, etc.).
+2. **Open the matching reference file** from the table above.
+3. **Grep for `initIndex`** (and language equivalents) to enumerate all call sites.
+4. **Update the install / dependency** first so the compiler/runtime flags all remaining issues.
+5. **Apply universal changes** (sections above) before language-specific ones.
+6. **Replace wait patterns** — search for `.wait()`, `waitTask`, `wait_task`, bang methods.
+7. **Verify** by running the existing test suite or a minimal integration test.
+
+## Direct Invocation
+
+If the skill doesn't trigger automatically, invoke it directly:
+
+- **`/algolia-migration`** — Load the full skill for any Algolia client upgrade task
+
+This is useful when the request is brief (e.g., "update my Algolia imports") and the skill might not auto-trigger.