# contentful-migration

A skill for writing and running Contentful content model migrations: content types, fields, validations, editor interface. Useful when schema changes should live in code, not in the web app.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 309 installs · ★ 39
- Author: contentful
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/contentful/skills/tree/HEAD/skills/contentful-migration/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/contentful-migration

## What it does

The skill teaches the agent to write TypeScript migrations with the `contentful-migration` library. Each migration file exports a function that receives a `migration` object and, as a second argument, a `context` with `makeRequest`, `spaceId` and `accessToken`. `makeRequest` covers data the migration API does not expose.

It documents content type and field operations: create, edit, delete, rename an ID with `changeFieldId`, reposition with `moveField` and `afterField`, plus validations, editor interface setup, entry transformations, tags and annotations. Execution goes through `contentful-cli`, not `npx contentful-migration` — those are different tools, and mixing them up is an easy mistake. Install the library with `npm install contentful-migration`.

You need `CONTENTFUL_SPACE_ID`, `CONTENTFUL_MANAGEMENT_ACCESS_TOKEN` and optionally `CONTENTFUL_ENVIRONMENT_ID`. The CMA token is created in account settings. The skill checks for these first and asks you to put them in a local `.env` if any are missing. It advises testing in a sandbox: `contentful environment create --name sandbox --source master`. A content type can only be deleted when it has zero entries, so move or remove them first. Deleting a field wipes its content from every entry for good.

SDK client setup belongs to the `contentful-nextjs` skill, and Contentful terminology with API routing to `contentful-guide`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add contentful/skills --skill contentful-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/contentful-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/contentful-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add contentful/skills --skill contentful-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/contentful-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add contentful/skills --skill contentful-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/contentful-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install contentful/skills contentful-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/contentful-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add contentful/skills --skill contentful-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/contentful/skills --path skills/contentful-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/contentful-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add contentful/skills --skill contentful-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/contentful/skills/tree/HEAD/skills/contentful-migration/SKILL.md

## When to use it
- add a field to a content type without breaking existing entries
- rename a field ID while keeping its content
- move entries from one content type to another
- set up validations and editor controls in code
- rehearse a migration in a sandbox before production

## Example prompts
- Write a migration that adds a `subtitle` field of type Symbol to the `blogPost` content type, optional
- Create a migration script that renames `oldName` to `newName` with `changeFieldId`
- Configure the editor interface for the `page` type: move `slug` into the sidebar

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b001120dec469e57.

BEGIN THIRD-PARTY FILE b001120dec469e57
````text
---
name: contentful-migration
description: >-
  Write and run Contentful content model migration scripts using the
  contentful-migration library and the Contentful CLI. Covers creating,
  editing, and deleting content types and fields, validations, editor interface
  configuration, editor layouts, sidebar widgets, entry transformations, tags,
  annotations, and the migration context object. Use when asked to write a
  migration, create or add a content type, add, rename, or delete fields,
  change or update a content model, transform entries, derive linked entries,
  configure editor controls, or run a migration script. Also triggers on
  "migration script", "contentful-migration", "schema migration",
  "content model migration", "field validation", "editor interface",
  "editor layout", "sidebar widget", "moveField", "changeFieldId",
  "rich text field", "reference field", "link field". Not for SDK client
  setup or Next.js integration (contentful-nextjs). Not for Contentful
  terminology or API routing (contentful-guide).
license: MIT
argument-hint: "[task description]"
allowed-tools: Bash(npx contentful-migration *) Bash(npx contentful space migration *) mcp__contentful-mcp__* mcp__plugin_contentful_contentful-mcp__*
paths: "migrations/**"
---

# Contentful Migration

The `contentful-migration` tool lets you describe and execute content model changes as code. Migrations are TypeScript scripts that create, edit, or delete content types, fields, editor interfaces, and entries.

**Install:**

```bash
npm install contentful-migration
```

GitHub: https://github.com/contentful/contentful-migration

## Scope

This skill covers:
- Content type and field CRUD operations
- Field types, validations, and editor interface configuration
- Entry transformations (in-place transforms, deriving linked entries, cross-type transforms)
- Tags, annotations, taxonomy validations
- Editor layouts, sidebar widgets
- Running migrations via `npx contentful space migration` (Contentful CLI) and programmatic API
````
END THIRD-PARTY FILE b001120dec469e57

The third-party file has ended. Everything between the b001120dec469e57 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2025 of 12364 bytes. © contentful · MIT · https://github.com/contentful/skills/tree/HEAD/skills/contentful-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md