> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. # Experiences upgrade skills > Install the skills and run an upgrade with your AI coding agent. ## Experiences upgrade agent: user guide Welcome, and thanks for helping us test the Experiences upgrade agent. This guide walks you through installing the [skills](https://assets.ctfassets.net/aeu1amk9b600/3iKrsB7ikwoL09OeRQFZHk/69aecef8325d25f1949734e45499feb3/exo-upgrade-skills-2026-08-20-115337.zip), running an upgrade end to end, and knowing what to expect at each step so nothing is surprising. It should take about 10 minutes to get to your first generated plan. **What this is:** a set of AI *skills* for Claude Code or Codex that analyze a legacy Contentful space and help you migrate it to Experiences. You talk to your agent in plain language. These skills do the mechanical work. **What this is not:** there is no app to launch and no program of ours you run directly. The skills are instructions plus bundled code that *your* agent runs. It is non-destructive — it reads your space and creates new ExO drafts for review; it never changes or deletes your existing content. ### 1. Prerequisites * Claude Code or Codex, installed and working. * Node.js 24 or newer — check with node --version . (nodejs.org) * Python 3 — check with python3 --version. macOS or Linux. Windows is not supported in this beta. * Your Contentful CMA token, Space ID, and environment (e.g. master ) for the space you want to upgrade. The agent asks for these; they are used only to talk to Contentful's API and are saved locally, never sent anywhere else. ### 2. Install the skills You received a zip named `experiences-upgrade-skills-date.zip`. Unzip it — you get one folder, `experiences-upgrade-skills/`, containing the skill set. Install it one of two ways: * Option A: with the skills CLI (recommended). * From the folder that contains `experiences-upgrade-skills/`: ```bash npx skills add ./experiences-upgrade-skills --copy -g --skill '*' --agent claude-code codex -y ``` * `npx` comes with Node, nothing extra to install. It fetches the small `skills` helper on demand. * `- -copy` copies the files in, so you can delete the unzipped folder afterward. the files in, so you can delete the unzipped folder afterward. * `- g` installs globally, so the skills work from any folder. * Drop `codex` (or `claude-code`) from `- -agent` if you only use one. Option B: copy the folders by hand (no CLI). If you'd rather not use npx , just copy each skill folder into your agent's skills directory: ```bash # Claude Code: cp -R experiences-upgrade-skills/* ~/.claude/skills/ # Codex: cp -R experiences-upgrade-skills/* ~/.agents/skills/ ``` Either way: restart your agent session afterward so it picks up the new skills. ### 3. Run an upgrade Open your agent in the folder you want to work from, then start the one entry-point skill: ```bash /contentful-exo-upgrade ``` That's the only skill you invoke by hand. It sets things up and then guides you through the rest of the flow conversationally. You say things like "upgrade" or "do a partial upgrade" and it runs the right skill for you. You do **not** run the other skills yourself. #### Step by step guide 1. **Setup + fetch your space:** the entry-point skill creates a local working folder (`.contentful-exo-upgrade/`, next to your `.git`), asks for your token / space / environment, and downloads your space into a local database. It then greets you with an inventory (content types, entry counts, locales). *Expect: a short Q\&A, then a summary of your space.* **(Optional) Codebase analysis:** if you have the space's website codebase handy, you can point the agent at it to map how pages compose from components. **Expect: a markdown analysis of your pages and components. This step is optional and read-only.** 2. **Upgrade:** generate the plan. Say upgrade . The agent analyzes the space, detects patterns and design properties, generates the ExO model (Component Types, Templates, Data Assemblies), publishes it to a Modeling Workspace you can review in the Contentful UI, and writes a plan. *Expect: draft entities created in your space for review. Nothing is published live; nothing existing is changed.* Modeling Workspace URL to open and review, plus a `plan.md`.\* 3. **Partial upgrade (recommended first):** Say partial upgrade to scope the migration to one page or a few content types instead of the whole space. The agent recommends a good starting point and publishes that slice as its own Modeling Workspace. *Expect: a focused, lower-risk first migration you can review before doing more.* 4. **Apply entries (the ETL):** only when you ask. Say \`apply the transformation / run the ETL to migrate the actual content entries into ExO Fragment and Experience drafts. **Expect: draft entities created in your space for review. Nothing is published live; nothing existing is changed.** You can stop after any step, review, and continue later from the same folder. Ask the agent questions about your space at any point ("how many entries do I have?") — it answers from the local database. #### Where the output goes Everything the agent produces stays in the visible working folder it created: ```bash / .contentful-exo-upgrade/ .env your token + space + environment (kept local, gitignored) spaces/-/ the downloaded copy of your space (local database) codebase-context// codebase analysis, if you ran it runs// one folder per upgrade run: plan.md the human-readable upgrade plan report.md a summary of the run artifacts/ the generated ExO model + supporting files ``` You can inspect or delete this folder any time. To start completely fresh, delete `.contentful-exo-upgrade/` and run `/contentful-exo-upgrade` again. ### 4. Updating to a newer build There's no auto-update during the beta. When we send a newer zip, re-run the install command from Section 2 (it overwrites the previous copy), then restart your agent session. ### 5. The skills, at a glance You only ever invoke /contentful-exo-upgrade . It runs the others for you as the flow progresses — this table is just so you know what each one does. | Skill | What it does | When it runs | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | **contentful-experiences-upgrade** | Entry point. Sets up the working folder, fetches your space, loads context, and greets you. | You run this first (the only one you invoke). | | **contentful-experiences-upgrade-codebase-analysis** | Analyzes your website codebase to map pages → components and the Contentful fields behind them. | Optional, early — if you point it at your code. | | **contentful-experiences-upgrade-plan** | The main upgrade workflow: analyze the space, generate the Experiences model, publish the Modeling Workspace, write the plan. | When you say "upgrade". | | **contentful-experiences-upgrade-partial-plan** | Scopes the plan to a page or a few content types and publishes that slice as its own Modeling Workspace. | When you say "partial upgrade". | | **contentful-experiences-upgrade-apply-modeling-workspace** | Publishes or updates the Modeling Workspace from the generated model. | Used by the upgrade / partial-upgrade steps. | | **contentful-experiences-upgrade-apply-entries** | The entry-level ETL: migrates content entries into ExO Fragment / Experience **drafts**. | Only when you explicitly ask to run it. | | **contentful-experiences-upgrade-save-chat** | Saves the conversation history to a file. | Any time, to keep a record. | ### 6. Glossary * **Experiences:** Contentful's model that separates content from presentation into Component Types (layout), Content Types (content), Data Assemblies (data), and Experiences / Fragments. * **Modeling Workspace:** the Contentful UI surface where you review and approve the AI-generated model before anything is migrated. * **Plan ( plan.md ):** a human-readable summary of the current model, detected patterns, the proposed Experiences model, and the mappings. * **Partial upgrade:** migrating a slice (one page or a few content types) instead of the whole space, so you can adopt Experiences incrementally. * **ETL / apply entries:** the step that moves your actual content entries into Experiences, created as drafts for review. * **Working folder (`.contentful-experiences-upgrade/`):** the local folder holding your downloaded space, analysis, and per-run outputs. Visible and safe to delete. ### 7. Feedback Please contact us with any feedback or questions: `konstantin.shtondenko@contentful.com `.