sanity-io/agent-toolkit

sanity-migration

Plans, implements, and reviews migrations from other CMSes and content systems into Sanity.

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/sanity-io/agent-toolkit --skill sanity-migration

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

Sanity Migration

Use this skill for CMS-to-Sanity migration work. Treat migration as a content strategy and ETL project, not a blind lift-and-shift.

Required Workflow

  1. Read references/general.md first.
  2. If the source platform is known, also read its guide:
  • AEM / Adobe Experience Manager: references/aem.md
  • Contentful: references/contentful.md
  • Strapi: references/strapi.md
  • Webflow: references/webflow.md
  • WordPress / WXR / Elementor: references/wordpress.md
  • Payload: references/payload.md
  • Drupal: references/drupal.md
  • Markdown / MDX / frontmatter files: references/markdown.md
  1. Before writing code, produce a short migration plan covering source access, content scope, schema decisions, extraction, transformation, import, validation, redirects, and cutover.
  2. 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.

Deliverables to Produce

For implementation or planning tasks, produce these artifacts or explain why they are not needed:

  • Content inventory: source types, counts, locales, status/draft scope, assets, and relationship types.
  • Source-to-Sanity mapping: document types, object types, references, Portable Text fields, asset fields, IDs, and skipped content.
  • Extraction approach: credentials/access needed, API/export commands, raw snapshot location, and known blind spots.
  • Transform/import plan: deterministic IDs, write order, asset handling, rich text conversion, validation, and rerun strategy.
  • Cutover plan: delta sync/content freeze, redirects, broken-link checks, SEO metadata, and manual cleanup.

Defaults

  • Use stable document IDs derived from source IDs, slugs, paths, or hashes.
  • Use createOrReplace, createIfNotExists, or sanity datasets import --replace so reruns converge.
  • Snapshot extracted source data to disk before transforming it.
  • Import or create referenced documents before documents that reference them.
  • Convert rich text to Portable Text instead of storing raw HTML or Markdown strings.
  • Upload assets to Sanity or the Media Library; do not leave production content dependent on legacy CDN URLs.
  • Track per-document quality issues and produce a validation summary before cutover.
  • Preserve legacy URLs and source IDs for redirects, QA, and future debugging.

Sanity Guardrails

  • Model what content is, not how the old site rendered it.
  • Use documents for reusable or independently managed entities; use objects for content owned by one document.
  • Use defineType, defineField, and defineArrayMember if authoring Sanity schemas.
  • Use image/file fields with uploaded Sanity assets or Media Library assets, not legacy CDN URLs.
  • Use Portable Text arrays for rich text and custom blocks; do not store raw HTML as the canonical body.
  • Run schema extraction and TypeGen after schema or GROQ query changes when the project uses TypeScript.
  • Deploy or apply schema changes before using MCP/content tools against the target dataset.

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:

bash
npx skills add sanity-io/agent-toolkit --skill sanity-best-practices

Stop and Ask

Stop before coding when any of these are unclear:

  • Source access path, credentials, export file, or database connection.
  • Target Sanity project/dataset or whether a scratch dataset should be used.
  • Draft, archived, scheduled, locale, or version history scope.
  • Whether media files should be migrated and whether asset URLs/files are accessible.
  • Whether the destination schema exists or should be designed as part of the migration.

Do Not Do This

  • Do not create random IDs for source-backed documents.
  • Do not fetch-then-create referenced documents; use deterministic IDs and createIfNotExists/createOrReplace.
  • Do not run bulk migrations through MCP content tools when NDJSON or scripts are appropriate.
  • Do not flatten locale fallback values into translations unless requested.
  • Do not leave TODOs for required media, authors, references, or rich text conversion.
  • Do not declare a migration done without count checks, sample checks, reference checks, and route/redirect checks.

Reference Map

Use references/general.md for shared migration principles and the platform references for source-specific extraction routes, modeling traps, and validation checks.

For source systems not explicitly covered, apply references/general.md and adapt the closest platform pattern:

  • API-first CMSes: start from Contentful, Strapi, or Payload.
  • Monolithic/page-builder systems: start from WordPress, Drupal, Webflow, or AEM.
  • HTML-heavy exports: start from the WordPress and Webflow rich-text guidance.
  • Markdown-first sources: start from references/markdown.md.

Relacionados por tarea

del mismo repositorio

Más Skills

Todos los Skills
sanity-io
Oficial

sanity-best-practices

Sanity development best practices for schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, webhooks, Blueprints, and framework integrations such as Next.js, Nuxt, Astro, Remix, SvelteKit, Angular, Hydrogen, the App SDK, and Studios or apps running in the Sanity Dashboard (defineApplication). Use this skill whenever working with Sanity schemas, defineType or defineField, GROQ or defineQuery, content modeling, Pr

Instalaciones / 1h
3
GitHub Stars
201
Actualizado
19 nov
sanity-io
Oficial

content-modeling-best-practices

Structured content modeling guidance for schema design, content architecture, content reuse, references versus embedded objects, separation of concerns, and taxonomies across Sanity and other headless CMSes. Use this skill when designing or refactoring content types, deciding field shapes, debating reusable versus nested content, planning omnichannel content models, or reviewing whether a schema is too page-shaped or presentation-driven.

Instalaciones / 1h
2
GitHub Stars
197
Actualizado
10 nov
sanity-io
Oficial

sanity-studio-upgrade

Produces a tailored Sanity Studio upgrade plan by inspecting the repository's installed versions, config, and source, then reporting only the breaking changes that actually apply. Covers Studio v3 and later; v2 projects are identified and redirected, not planned. Use this skill whenever someone wants to upgrade, migrate, or modernize a Sanity Studio across one or more major versions from v3 onward, asks what will break if they bump the sanity package, asks why their Studio broke after an upgrade

Instalaciones / 1h
2
GitHub Stars
196
Actualizado
27 oct
sanity-io
Oficial

portable-text-conversion

Convert HTML and Markdown content into Portable Text blocks for Sanity. Use when migrating content from legacy CMSs, importing HTML or Markdown into Sanity, building content pipelines that ingest external content, converting rich text between formats, or programmatically creating Portable Text documents. Covers @portabletext/markdown (markdownToPortableText), @portabletext/block-tools (htmlToBlocks), custom deserializers, and the Portable Text specification for manual block construction.

Instalaciones / 1h
1
GitHub Stars
191
Actualizado
14 oct