Index of every page on this site: llms.txt
All skills
sanity-io avatar

/sanity-migration

@828641f official
by Sanitysanity-io/agent-toolkit201 stars
32
Run it yourself

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, CMS APIs, database dumps, static HTML, or when designing extraction, transformation, Portable Text conversion, asset migration, redirects, validation, and cutover workflows.

Use this Skill: https://skilld.dev/gh/sanity-io/agent-toolkit/sanity-migration

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈118 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈18k more on demand in 9 files.

Description uses 5.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈472 characters, or 5.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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
  3. Before writing code, produce a short migration plan covering source access, content scope, schema decisions, extraction, transformation, import, validation, redirects, and cutover.
  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.

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:

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides a robust framework for migrating content from various CMS platforms to Sanity. It emphasizes security best practices by requiring user confirmation for credential access and advocating for a human-in-the-loop workflow where generated scripts are reviewed by the user before execution.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at 828641f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago
  • sanity
  • cms
  • migration
  • etl
  • contentful
  • wordpress
  • strapi
  • payload
  • drupal
  • portable-text

README badge

README badge for sanity-io/agent-toolkit/sanity-migration

Plans and implements CMS-to-Sanity migrations from AEM, Contentful, Strapi, Webflow, WordPress, Payload, Drupal, Markdown, and database exports. Covers content inventory, schema mapping, extraction, Portable Text conversion, asset migration, validation, and cutover workflows with deterministic IDs and repeatable scripts.

Generated from the current SKILL.md.

Does this skill handle migrations from WordPress, Contentful, Strapi, and other specific CMSes?
Yes. The skill includes platform-specific guides for AEM, Contentful, Strapi, Webflow, WordPress, Payload, Drupal, and Markdown/MDX sources. For other systems, it provides a general migration framework to adapt.
What does this skill actually produce—code, a plan, or both?
The skill guides you to produce a migration plan first (content inventory, source-to-Sanity mapping, extraction approach, transform/import plan, cutover plan), then helps you write deterministic, repeatable migration scripts and validation checks.
Does this handle asset migration and rich text conversion?
Yes. The skill requires converting rich text to Portable Text, uploading assets to Sanity instead of relying on legacy CDN URLs, and producing validation checks before cutover.
Can I use this for one-off content operations or bulk migrations through MCP tools?
No. The skill explicitly prefers deterministic, repeatable scripts over one-off operations and discourages running bulk migrations through MCP content tools when NDJSON or scripts are appropriate.

Generated from the current SKILL.md. These answers refresh after source changes.