Import design system

Experiences codebase analysis

ExO Codebase Analysis: User Guide

Thanks for helping us with the ExO upgrade. This package contains one AI skill: codebase analysis. You point it at your website’s codebase, it maps how your pages are built from components and which Contentful fields power each one, and it writes that analysis to a folder.

1. Prerequisites

  • Claude Code or Codex, installed and working.
  • Node.js 24 or newer (node --version) on Nodejs
  • macOS or Linux. Windows is not supported in this beta.
  • A local copy of your website’s codebase (the repo that renders your Contentful content).
  • Your Contentful CMA token, Space ID, and environment for the space the site uses. The skill needs these to read your content model (the GraphQL schema). They are used only to talk to Contentful’s API and are stored locally.

2. Install the skill

You received a zip named exo-codebase-analysis-<date>.zip. Unzip this folder, which includes exo-codebase-analysis/, containing the skill. Install it one of two ways:

  • From the folder that contains exo-codebase-analysis/:
$npx skills add ./exo-codebase-analysis --copy -g --skill '*'--agent claude-code codex -y
  • npx comes with Node (nothing extra to install). --copy copies the files in and -g installs globally, so it works from any folder. Drop codex (or claude-code) if you only use one.

Option B: copy the folder by hand (no CLI)

  • Copy the skill folder into your agent’s skills directory:
$# Claude Code:
$cp -R exo-codebase-analysis/contentful-exo-upgrade-codebase-analysis ~/.claude/skills/
$# Codex:
$cp -R exo-codebase-analysis/contentful-exo-upgrade-codebase-analysis ~/.agents/skills/

<Info> For both options: restart your agent session afterward. <Info>

3. Run the analysis

Open your agent in your website’s codebase folder and start the skill:

$/contentful-exo-upgrade-codebase-analysis

What happens:

  1. It confirms your codebase path and detects your framework (Next.js, React, etc.).
  2. It asks for your Contentful CMA token / space / environment (to read your content model) — provide these when prompted.
  3. It discovers your pages and shows you the list, then stops so you can pick which pages to analyze (a subset, or all). This is your choice, analyze everything, or just a few pages to start.
  4. For each selected page it traces the component tree and writes one markdown file per component, plus a page router view. It reads your source to understand it and writes only into the analysis folder below. It does not change your code and does not touch your Contentful content.

4. What you get (the output)

Everything is written inside your codebase, under a visible folder:

$<your-codebase>/.contentful-exo-upgrade/codebase-analysis/
$├── codebase-analysis.json # a little run metadata
$├── pages.json / pages.md # every page found, and which you analyzed
$├── Contentful-GraphQL.json/.gql # your content model, mapped
$└── <mirror of your source tree>/ # one .md per analyzed component

5. Send the result back to us

This is the important part. When the run finishes:

  • Zip the analysis folder:
$cd <your-codebase>/.contentful-exo-upgrade
$zip -r codebase-analysis.zip codebase-analysis
  • Send us codebase-analysis.zip (however we arranged, either via email, Slack or shared drive). That folder is everything we need — you don’t send us your source code, just the generated analysis.

6. Updating to a newer build

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) and restart your agent session.

7. Start over

  • Re-run analysis: just invoke /contentful-exo-upgrade-codebase-analysis again — re-runs are cheap (unchanged files are skipped) and you can select more pages.
  • Clean slate: delete <your-codebase>/.contentful-exo-upgrade/codebase-analysis/.

8. Feedback

Please contact us with any feedback or questions: konstantin.shtondenko@contentful.com .