sanity-migration

Name: sanity-migration
Author: sanity-io

7.9kinstalls22forks

How to install sanity-migration?

sanity-io/agent-toolkit/sanity-migration

$npx -y skills add sanity-io/agent-toolkit --skill sanity-migration

Installs into the current project.

Summary

Plans, implements, and reviews migrations from other CMSes and content systems into Sanity. Use when migrating or replatforming to Sanity from AEM, Adobe Experience Manager, Contentful, Strapi, Webflow, WordPress, Payload, Drupal, Markdown/MDX/frontmatter files, WXR/XML exports,

Files · 1

View on GitHub

SKILL.md

1	# Sanity Migration
2
3	Use this skill for CMS-to-Sanity migration work. Treat migration as a content strategy and ETL project, not a blind lift-and-shift.
4
5	## Required Workflow
6
7	1. Read `references/general.md` first.
8	2. If the source platform is known, also read its guide:
9	- AEM / Adobe Experience Manager: `references/aem.md`
10	- Contentful: `references/contentful.md`
11	- Strapi: `references/strapi.md`
12	- Webflow: `references/webflow.md`
13	- WordPress / WXR / Elementor: `references/wordpress.md`
14	- Payload: `references/payload.md`
15	- Drupal: `references/drupal.md`
16	- Markdown / MDX / frontmatter files: `references/markdown.md`
17	3. Before writing code, produce a short migration plan covering source access, content scope, schema decisions, extraction, transformation, import, validation, redirects, and cutover.
18	4. Prefer deterministic, repeatable scripts for real migrations. Write and review migration scripts, mappings, and validation checks; do not rely on one-off content operations for large content volumes.
19
20	## Deliverables to Produce
21
22	For implementation or planning tasks, produce these artifacts or explain why they are not needed:
23
24	- Content inventory: source types, counts, locales, status/draft scope, assets, and relationship types.
25	- Source-to-Sanity mapping: document types, object types, references, Portable Text fields, asset fields, IDs, and skipped content.
26	- Extraction approach: credentials/access needed, API/export commands, raw snapshot location, and known blind spots.
27	- Transform/import plan: deterministic IDs, write order, asset handling, rich text conversion, validation, and rerun strategy.
28	- Cutover plan: delta sync/content freeze, redirects, broken-link checks, SEO metadata, and manual cleanup.
29
30	## Defaults
31
32	- Use stable document IDs derived from source IDs, slugs, paths, or hashes.
33	- Use `createOrReplace`, `createIfNotExists`, or `sanity dataset import --replace` so reruns converge.
34	- Snapshot extracted source data to disk before transforming it.
35	- Import or create referenced documents before documents that reference them.
36	- Convert rich text to Portable Text instead of storing raw HTML or Markdown strings.
37	- Upload assets to Sanity or the Media Library; do not leave production content dependent on legacy CDN URLs.
38	- Track per-document quality issues and produce a validation summary before cutover.
39	- Preserve legacy URLs and source IDs for redirects, QA, and future debugging.
40
41	## Sanity Guardrails
42
43	- Model what content is, not how the old site rendered it.
44	- Use documents for reusable or independently managed entities; use objects for content owned by one document.
45	- Use `defineType`, `defineField`, and `defineArrayMember` if authoring Sanity schemas.
46	- Use image/file fields with uploaded Sanity assets or Media Library assets, not legacy CDN URLs.
47	- Use Portable Text arrays for rich text and custom blocks; do not store raw HTML as the canonical body.
48	- Run schema extraction and TypeGen after schema or GROQ query changes when the project uses TypeScript.
49	- Deploy or apply schema changes before using MCP/content tools against the target dataset.
50
51	For deeper Sanity implementation guidance, use `sanity-best-practices` if it is already available. If it is not installed, tell the user they can add it with:
52
53	```bash
54	npx skills add sanity-io/agent-toolkit --skill sanity-best-practices
55	```
56
57	## Stop and Ask
58
59	Stop before coding when any of these are unclear:
60
61	- Source access path, credentials, export file, or database connection.
62	- Target Sanity project/dataset or whether a scratch dataset should be used.
63	- Draft, archived, scheduled, locale, or version history scope.
64	- Whether media files should be migrated and whether asset URLs/files are accessible.
65	- Whether the destination schema exists or should be designed as part of the migration.
66
67	## Do Not Do This
68
69	- Do not create random IDs for source-backed documents.
70	- Do not fetch-then-create referenced documents; use deterministic IDs and `createIfNotExists`/`createOrReplace`.
71	- Do not run bulk migrations through MCP content tools when NDJSON or scripts are appropriate.
72	- Do not flatten locale fallback values into translations unless requested.
73	- Do not leave TODOs for required media, authors, references, or rich text conversion.
74	- Do not declare a migration done without count checks, sample checks, reference checks, and route/redirect checks.
75
76	## Reference Map
77
78	Use `references/general.md` for shared migration principles and the platform references for so

People who liked this also viewed

6 picks

Type

sanity-migration

7.9kinstalls22forks

View on GitHub

How to install sanity-migration?

sanity-io/agent-toolkit/sanity-migration

$npx -y skills add sanity-io/agent-toolkit --skill sanity-migration

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Sanity Migration
2
3	Use this skill for CMS-to-Sanity migration work. Treat migration as a content strategy and ETL project, not a blind lift-and-shift.
4
5	## Required Workflow
6
7	1. Read `references/general.md` first.
8	2. If the source platform is known, also read its guide:
9	- AEM / Adobe Experience Manager: `references/aem.md`
10	- Contentful: `references/contentful.md`
11	- Strapi: `references/strapi.md`
12	- Webflow: `references/webflow.md`
13	- WordPress / WXR / Elementor: `references/wordpress.md`
14	- Payload: `references/payload.md`
15	- Drupal: `references/drupal.md`
16	- Markdown / MDX / frontmatter files: `references/markdown.md`
17	3. Before writing code, produce a short migration plan covering source access, content scope, schema decisions, extraction, transformation, import, validation, redirects, and cutover.
18	4. Prefer deterministic, repeatable scripts for real migrations. Write and review migration scripts, mappings, and validation checks; do not rely on one-off content operations for large content volumes.
19
20	## Deliverables to Produce
21
22	For implementation or planning tasks, produce these artifacts or explain why they are not needed:
23
24	- Content inventory: source types, counts, locales, status/draft scope, assets, and relationship types.
25	- Source-to-Sanity mapping: document types, object types, references, Portable Text fields, asset fields, IDs, and skipped content.
26	- Extraction approach: credentials/access needed, API/export commands, raw snapshot location, and known blind spots.
27	- Transform/import plan: deterministic IDs, write order, asset handling, rich text conversion, validation, and rerun strategy.
28	- Cutover plan: delta sync/content freeze, redirects, broken-link checks, SEO metadata, and manual cleanup.
29
30	## Defaults
31
32	- Use stable document IDs derived from source IDs, slugs, paths, or hashes.
33	- Use `createOrReplace`, `createIfNotExists`, or `sanity dataset import --replace` so reruns converge.
34	- Snapshot extracted source data to disk before transforming it.
35	- Import or create referenced documents before documents that reference them.
36	- Convert rich text to Portable Text instead of storing raw HTML or Markdown strings.
37	- Upload assets to Sanity or the Media Library; do not leave production content dependent on legacy CDN URLs.
38	- Track per-document quality issues and produce a validation summary before cutover.
39	- Preserve legacy URLs and source IDs for redirects, QA, and future debugging.
40
41	## Sanity Guardrails
42
43	- Model what content is, not how the old site rendered it.
44	- Use documents for reusable or independently managed entities; use objects for content owned by one document.
45	- Use `defineType`, `defineField`, and `defineArrayMember` if authoring Sanity schemas.
46	- Use image/file fields with uploaded Sanity assets or Media Library assets, not legacy CDN URLs.
47	- Use Portable Text arrays for rich text and custom blocks; do not store raw HTML as the canonical body.
48	- Run schema extraction and TypeGen after schema or GROQ query changes when the project uses TypeScript.
49	- Deploy or apply schema changes before using MCP/content tools against the target dataset.
50
51	For deeper Sanity implementation guidance, use `sanity-best-practices` if it is already available. If it is not installed, tell the user they can add it with:
52
53	```bash
54	npx skills add sanity-io/agent-toolkit --skill sanity-best-practices
55	```
56
57	## Stop and Ask
58
59	Stop before coding when any of these are unclear:
60
61	- Source access path, credentials, export file, or database connection.
62	- Target Sanity project/dataset or whether a scratch dataset should be used.
63	- Draft, archived, scheduled, locale, or version history scope.
64	- Whether media files should be migrated and whether asset URLs/files are accessible.
65	- Whether the destination schema exists or should be designed as part of the migration.
66
67	## Do Not Do This
68
69	- Do not create random IDs for source-backed documents.
70	- Do not fetch-then-create referenced documents; use deterministic IDs and `createIfNotExists`/`createOrReplace`.
71	- Do not run bulk migrations through MCP content tools when NDJSON or scripts are appropriate.
72	- Do not flatten locale fallback values into translations unless requested.
73	- Do not leave TODOs for required media, authors, references, or rich text conversion.
74	- Do not declare a migration done without count checks, sample checks, reference checks, and route/redirect checks.
75
76	## Reference Map
77
78	Use `references/general.md` for shared migration principles and the platform references for so

People who liked this also viewed

6 picks

Type