Content Graph Query Migrations

A Claude Code plugin for migrating C# SDK queries from Search & Navigation (EPiServer Find) to the Optimizely Graph SDK (Optimizely.Graph.Cms.Query).

Getting Started

1. Install Claude Code

If you don't have Claude Code installed, follow the official installation guide.

2. Install the plugin

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add episerver/content-graph-sdk-migrations
/plugin install cg-migrate@content-graph-sdk-migrations

This is a one-time setup. The plugin will load automatically on every future Claude Code session.

3. Prepare your codebase

Before running any migration skills, ensure your target project is in a clean state:

1. Create a dedicated branch — check out a clean branch with no pending changes
2. Build passes — the solution should compile without errors
3. Tests pass — all existing tests should be green

Starting from a clean, passing state prevents the agent from conflating pre-existing issues with migration changes.

Usage

There are three ways to use this plugin depending on how much control you need.

Full automation

Run the entire migration pipeline in one shot. Claude will scan your codebase, apply transformations, and validate the results — pausing only when a pattern requires a manual decision.

/cg-migrate:migrate-all --project path/to/Solution.sln

This is the recommended starting point for most projects. It runs the scan, transform, and validate steps in sequence and produces a final migration report.

Skill-by-skill

Run each stage independently for more control over the process. This is useful when you want to review the scan results before transforming, or re-run validation after manual fixes.

/cg-migrate:migrate-scan --project path/to/Solution.sln

Scans for all Search & Navigation API usage and produces a structured inventory at .cg-migrations/migrate-scan/scan-report.md. Review this to understand the scope before proceeding.

/cg-migrate:migrate-transform --project path/to/Solution.sln

Applies translation rules to every file identified by the scan. Manages NuGet package swaps, applies code transformations, and flags anything requiring manual review.

/cg-migrate:migrate-validate --project path/to/Solution.sln

Builds the project, parses compiler errors, and maps each failure back to the migration rule that caused it. Offers to re-run transform on failed files for a second pass.

Single-query translation

Translate an individual file or code snippet without running a full migration. This is useful for understanding how a specific S&N pattern maps to the Graph SDK, or for migrating files one at a time.

/cg-migrate:migrate-map

Then point Claude at the file or paste the code you want translated. The skill contains the complete mapping reference — namespaces, DI registration, query/filter/facet/sort/pagination translations, and edge cases.

Migration artifacts

The plugin writes all reports, decisions, and build logs to a .cg-migrations/ directory at the root of your target project:

.cg-migrations/
  migrate-scan/          # Scan reports (timestamped)
  migrate-transform/     # Transform reports
  migrate-validate/      # Build output and validation reports
  migrate-decisions.md   # User decisions for manual patterns

This directory is separate from .claude/ (Claude Code's own configuration) to avoid permission warnings. You may want to add .cg-migrations/ to your .gitignore.

Updating

To pull the latest migration patterns and skills:

/plugin marketplace update content-graph-sdk-migrations

Current Status

Skill	Status
migrate-scan	Available
migrate-map	Available
migrate-transform	Available
migrate-validate	Available
migrate-all	Available