feat: add algolia-migration skill for API client upgrades by MarioAlexandruDan · Pull Request #26 · algolia/skills

MarioAlexandruDan · 2026-05-20T12:39:10Z

Covers 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, and Swift v8→v9. Dart is a new client with no legacy version, so it's excluded from scope. Includes universal breaking-change patterns, per-language reference files with primary-source code examples, 5 evals, and marketplace registration.

What does this skill do?

Gives AI agents accurate, language-specific migration recipes so developers can upgrade Algolia backend clients to the current major version without reading long changelogs or guessing renamed methods.

Checklist

python3 scripts/validate_skills.py . passes (0 errors)
Skill description is under 1024 chars and includes WHEN and WHEN NOT to trigger
evals/evals.json exists with at least 1 realistic prompt
Skill is self-contained — no ../other-skill/ references
Registered in .claude-plugin/marketplace.json (new skills only)
Goes in skills/ here if useful to customers; internal-only skills → algolia/internal-skills

Covers 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, Swift v8→v9, and Dart (new client). Includes universal breaking-change patterns, per-language reference files with primary-source code examples, 5 evals, and marketplace registration.

- dart.md: replace non-existent saveObjects with saveObject/batch pattern - go.md: fix cross-app copy (SettingsResponse→IndexSettings JSON round-trip, handle NewClient errors) - evals: add coverage for Java, C#, Kotlin, Scala, Swift, Dart (11 evals total) - README: fix trailing whitespace on instantsearch table row

…ation go.md: handle json.Marshal/Unmarshal errors in cross-app copy java.md: fix replaceAllObjects (args not ReplaceAllObjectsParams model), fix browseObjects (Iterable<T> pattern, not consumer callback) kotlin.md: searchParamsObject -> searchParams parameter name ruby.md: replace_all_objects uses positional args, not keyword scopes: evals: fix Python save_objects body= -> objects=, Java saveObjects singular/plural and waitForTasks pattern

ReplaceAllObjects, PartialUpdateObjects, and BrowseObjects all use variadic option functions, not params structs: - ReplaceAllObjects(indexName, objects, WithScopes([...])) - PartialUpdateObjects(indexName, objects, WithCreateIfNotExists(false)) - BrowseObjects(indexName, BrowseParamsObject{}, WithAggregator(func(any,error))) Also fixes BrowseObjects aggregator callback type: func(any, error) not func(*search.BrowseResponse)

saveObjects(String, Iterable, boolean) does not exist — the 3-arg overload takes RequestOptions. Use the 4-arg form: saveObjects(indexName, objects, true, null)

… files csharp.md: - OperationIndexAsync: Operation = OperationType.Copy/Move (not string) - BrowseObjectsAsync: returns IEnumerable<T>, use foreach (not callback) - Helper changes note corrected accordingly php.md: - browseObjects returns ObjectIterator, iterate with foreach (not callback) - Wait pattern: saveObject singular for single-task wait; saveObjects with third bool arg for multi-object wait (saveObjects result is array) ruby.md: - browse_objects block receives individual hits, not page response python.md: - SearchParams import: from algoliasearch.search.models import SearchParams javascript.md: - accountCopyIndex: clarify it is on the algoliasearch meta-package client evals.json: - eval #7 C#: SaveObjectsAsync returns List<BatchResponse>; use built-in waitForTasks param instead of chaining WaitForTaskAsync on list result

go.md: remove spurious pointer dereference on TaskID (int64 not *int64) kotlin.md: browseRules/browseSynonyms helpers don't exist in v3; replace cross-app copy with confirmed browseObjects + note about rules/synonyms swift.md: browseObjects requires browseParams: + aggregator: labels (not trailing closure); add saveObjects helper with waitForTasks param

…Type enum

…g round python.md: transformation helpers require TransformationOptions object not transformation_region string at init javascript.md: split replaceAllRules/replaceAllSynonyms rename rows — rules use clearExistingRules:true, synonyms use replaceExistingSynonyms:true csharp.md: ChunkedBatch/IndexExists helpers have Async suffix php.md: generateSecuredApiKey is static and takes a plain array, not a typed SecuredApiKeyRestrictions model

WithChunkedBatchWaitForTasks -> WithWaitForTasks (correct ChunkedBatchOption) WithReplaceAllObjectsBatchSize -> WithBatchSize (correct option, former does not exist)

Java, PHP and C# use Iterable/IEnumerable/ObjectIterator (foreach loop), not an aggregator callback — clarify universal #6 accordingly

…erable Official docs and source confirm BrowseObjectsAsync accepts an Action<T> aggregator, not an IEnumerable<T>. Fix SKILL.md universal #6 accordingly.

… docs Rewrote every language reference file based on content fetched directly from https://www.algolia.com/doc/libraries/sdk/upgrade/<lang>.md: - Full method rename tables sourced from official docs - Correct helper signatures (ReplaceAllObjectsParams struct for Go, browseObjects iterator for PHP, aggregator callback for C#/Java/Ruby) - Cross-app copy patterns for all languages - Transformation helpers with correct init requirements - waitForApiKey, waitForAppTask documented for all languages - Complete Recommend API rename tables included Key corrections vs previous version: - Go: ReplaceAllObjects/PartialUpdateObjects/BrowseObjects use correct struct/params forms from official docs - PHP: browseObjects returns iterator (foreach), not aggregator - Ruby: browse block receives full page response (response.hits), not hits - C#: BrowseObjectsAsync confirmed aggregator (reverted IEnumerable fix) - Java: browseObjects uses aggregator callback (confirmed from docs) - Python: save_objects uses objects= param; transformation via SearchConfig - SKILL.md §6: Java moved to aggregator group

…e guides All 11 language reference files now mirror the content of the official Algolia SDK upgrade guides at algolia.com/doc/libraries/sdk/upgrade/<lang>. Includes full method rename tables, all helper changes, cross-app copy patterns, transformation helpers, and wait helpers per language. dart.md: verified against actual client source — fixed wrong package names (algolia_client_abtesting_v3, removed non-existent analytics/ingestion), waitTask/waitAppTask/waitKeyCreation method names, SearchForHits direct usage, correct enum values.

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Fluf22

A few other generic observations:

add a trailing newline at the end of each reference file
cleanup the doc-site rendering artifacts in reference files
- code fence decorators (icon=, theme=, highlight=, expandable)
- absolute /doc/ paths
- JSX/MDX components

It's noise for the agents, or it can even break their tool calls (no trailing newline can mess with cat, diff, etc)

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

- Delete references/kotlin.md (out of scope) - Delete references/dart.md (new client, no migration needed) - Remove Kotlin eval (#8) from evals.json - SKILL.md: remove Kotlin from supported migrations table, description, and browse aggregator list - marketplace.json: remove Kotlin from description

…files - Strip code fence decorators (icon=, theme=, highlight=, expandable) so language hints are bare identifiers agents can parse - Remove JSX/MDX tags (<Tip>, <Note>, </Tip>, </Note>) while preserving their content - Convert absolute /doc/ paths to plain text (broken outside algolia.com) - Add trailing newlines to all 9 reference files

…v4 client

…inst v4 client

…ection

…on init

…SearchConfig/client init

… correct namespaces

…prehension syntax

…Objects return type, scopes optional

…d, browse pattern accuracy, remove Kotlin/Dart from README

…val expectation; scope marketplace description

…king Dart code

- Strip doc-site rendering artifacts (code fence decorators, JSX components, /doc/ links) - Use direct enum access (OperationType.Copy, ScopeType.Rules, SynonymType.Synonym) instead of verbose .entries.first - Mark scopes optional with default in replaceAllObjects - Fix SettingsResponse → IndexSettings conversion in copyIndexBetweenApplications - Add saveObjectsWithTransformation, replaceAllObjectsWithTransformation, partialUpdateObjectsWithTransformation sections - Bring Kotlin into scope in SKILL.md, marketplace.json, and README

Fills the empty slot in the eval IDs (1–7, 9–11) and brings Kotlin to parity with the other 9 supported languages. Exercises imports, type-wrapper removal, DSL removal, initIndex removal, and the saveObjects+waitForTasks pattern.

…ides - waitForTask maxRetries default corrected to 100 in all languages - transformation helper sections aligned to the transformationOptions API: JS transformationOptions prop (transformation deprecated), Java/C# withTransformation + deprecation notes, Go TransformationOptions (not IngestionTransporter), Python transformation_options, PHP client-configuration wording - add missing WithTransformation sections for Swift and Ruby, restore Kotlin sections with the withTransformation setup - consistent 'In version X and later:' phrasing across references

…ation # Conflicts: # .claude-plugin/marketplace.json # README.md

… feat/add-algolia-migration

…ade guides Mechanical copy of doc/libraries/sdk/upgrade/*.mdx from docs-new main (includes algolia/docs-new#904) with doc-site formatting stripped: frontmatter converted to plain title/description, code-fence decorators removed, Note/Tip components flattened to indented text, internal /doc/ links flattened to plain text. Anchor and external links are kept.

Fluf22

Great, thanks
Let's put it reviewable so the algolia/skills team can give its opinion

Copilot

Pull request overview

Adds a new algolia-migration skill to guide agents through major-version upgrades of Algolia API clients across multiple backend languages, with per-language reference guides, eval prompts, and marketplace registration.

Changes:

Introduces skills/algolia-migration skill definition plus “universal breaking changes” guidance.
Adds language-specific migration reference docs (JS, Python, Go, PHP, Java, C#, Ruby, Kotlin, Scala, Swift).
Registers the skill in the marketplace and lists it in the repo README; adds eval scenarios.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`skills/algolia-migration/SKILL.md`	Skill frontmatter + universal migration guidance and workflow.
`skills/algolia-migration/references/javascript.md`	JS v4 → v5 migration reference.
`skills/algolia-migration/references/python.md`	Python v3 → v4 migration reference.
`skills/algolia-migration/references/go.md`	Go v3 → v4 migration reference.
`skills/algolia-migration/references/php.md`	PHP v3 → v4 migration reference.
`skills/algolia-migration/references/java.md`	Java v3 → v4 migration reference.
`skills/algolia-migration/references/csharp.md`	C# v6 → v7 migration reference.
`skills/algolia-migration/references/ruby.md`	Ruby v2 → v3 migration reference.
`skills/algolia-migration/references/kotlin.md`	Kotlin v2 → v3 migration reference.
`skills/algolia-migration/references/scala.md`	Scala v1 → v2 migration reference.
`skills/algolia-migration/references/swift.md`	Swift v8 → v9 migration reference.
`skills/algolia-migration/evals/evals.json`	Adds eval prompts/expectations for common upgrade scenarios.
`README.md`	Adds `algolia-migration` to the skills list and install examples.
`.claude-plugin/marketplace.json`	Registers the new skill in the marketplace manifest.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- python.md: fix invalid v3 save_objects example (positional arg after keyword arg) - SKILL.md: make waitForTask pseudo-signature language-agnostic, point to per-language references - evals.json: align JS expected_output with waitForTasks: true expectation - evals.json: fix Go SaveObjects expectation to match reference (index name as first argument)

MarioAlexandruDan marked this pull request as draft May 20, 2026 12:39

MarioAlexandruDan added 10 commits May 20, 2026 15:49

fix(algolia-migration): correct Java saveObjects overload in eval #6

1591e01

saveObjects(String, Iterable, boolean) does not exist — the 3-arg overload takes RequestOptions. Use the 4-arg form: saveObjects(indexName, objects, true, null)

fix(algolia-migration): csharp.md method renames table uses Operation…

33b6ae9

…Type enum

fix(algolia-migration): source-verified option function names in go.md

8cf8dcc

WithChunkedBatchWaitForTasks -> WithWaitForTasks (correct ChunkedBatchOption) WithReplaceAllObjectsBatchSize -> WithBatchSize (correct option, former does not exist)

fix(algolia-migration): SKILL.md browse pattern varies by language

da850a5

Java, PHP and C# use Iterable/IEnumerable/ObjectIterator (foreach loop), not an aggregator callback — clarify universal #6 accordingly

MarioAlexandruDan marked this pull request as ready for review May 20, 2026 14:26

MarioAlexandruDan marked this pull request as draft May 20, 2026 14:32

MarioAlexandruDan self-assigned this May 20, 2026

MarioAlexandruDan added 3 commits May 21, 2026 10:59

fix(algolia-migration): C# browse uses aggregator callback, not IEnum…

f5bc4f8

…erable Official docs and source confirm BrowseObjectsAsync accepts an Action<T> aggregator, not an IEnumerable<T>. Fix SKILL.md universal #6 accordingly.

Fluf22 reviewed May 21, 2026

View reviewed changes

Comment thread .claude-plugin/marketplace.json Outdated

Update .claude-plugin/marketplace.json

f0ee057

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Fluf22 reviewed May 22, 2026

View reviewed changes

MarioAlexandruDan and others added 9 commits May 22, 2026 13:20

Update skills/algolia-migration/SKILL.md

3531196

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Update skills/algolia-migration/SKILL.md

c0740e7

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Update skills/algolia-migration/SKILL.md

57dd946

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Update skills/algolia-migration/SKILL.md

888112d

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Update skills/algolia-migration/SKILL.md

3306fdf

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

Update README.md

09bd626

Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>

feat(algolia-migration): remove dart.md (new client, no migration)

cf050dd

MarioAlexandruDan added 13 commits May 29, 2026 15:19

fix(csharp): correct API signatures and code examples against v7 client

cb9f2cf

fix(go): correct API signatures, option names, and constants against …

09e5bd7

…v4 client

fix(java): correct helper signatures, return types, and overloads aga…

5a7ec20

…inst v4 client

fix(javascript): replaceAllObjects scopes is optional, not required

72a71d1

docs(skill): note JS v5 accountCopyIndex exception in AccountClient s…

37cb451

…ection

fix(php): correct helper signatures, iterator usage, and transformati…

ae4aef6

…on init

fix(python): invalid syntax in v3 examples, scopes optional, correct …

36c64d1

…SearchConfig/client init

fix(ruby): browse block receives individual records, scopes optional,…

7ba5fe8

… correct namespaces

fix(scala): return types, browseParams name, required params, for-com…

29e919d

…prehension syntax

fix(swift): instance methods not static, required browse params, save…

8d648db

…Objects return type, scopes optional

fix(review): SaveObjectsAsync return type, scopes optional in SKILL.m…

9306933

…d, browse pattern accuracy, remove Kotlin/Dart from README

fix(js): saveObjects returns BatchResponse[], use waitForTasks; fix e…

603fb88

…val expectation; scope marketplace description

fix(evals): Dart eval #11 should expect out-of-scope refusal, not wor…

6d73bae

…king Dart code

MarioAlexandruDan marked this pull request as ready for review June 2, 2026 07:59

MarioAlexandruDan marked this pull request as draft June 2, 2026 07:59

MarioAlexandruDan added 8 commits June 2, 2026 11:18

fix(go,php): residual option names in transformation sections

2b49b5e

feat(evals): add Kotlin v2→v3 eval at ID 8

13c8f20

Fills the empty slot in the eval IDs (1–7, 9–11) and brings Kotlin to parity with the other 9 supported languages. Exercises imports, type-wrapper removal, DSL removal, initIndex removal, and the saveObjects+waitForTasks pattern.

Merge branch 'main' into feat/add-algolia-migration

4f3f9a7

Merge remote-tracking branch 'origin/main' into feat/add-algolia-migr…

3b01aa4

…ation # Conflicts: # .claude-plugin/marketplace.json # README.md

Merge remote-tracking branch 'origin/feat/add-algolia-migration' into…

ef8ddad

… feat/add-algolia-migration

Fluf22 reviewed Jul 6, 2026

View reviewed changes

MarioAlexandruDan marked this pull request as ready for review July 6, 2026 18:29

MarioAlexandruDan enabled auto-merge (squash) July 7, 2026 06:11

MarioAlexandruDan requested a review from Copilot July 9, 2026 07:57

Copilot started reviewing on behalf of MarioAlexandruDan July 9, 2026 08:01 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add algolia-migration skill for API client upgrades#26

feat: add algolia-migration skill for API client upgrades#26
MarioAlexandruDan wants to merge 47 commits into
mainfrom
feat/add-algolia-migration

MarioAlexandruDan commented May 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Fluf22 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Fluf22 left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

MarioAlexandruDan commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this skill do?

Checklist

Uh oh!

Uh oh!

Fluf22 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Fluf22 left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MarioAlexandruDan commented May 20, 2026 •

edited

Loading