Your AI agent knows how to code. These skills teach it Contentful.

AI coding agents write great code but know nothing about your content model, your SDK patterns, or which of Contentful's five APIs to reach for. Contentful Skills fixes that — curated instructions, reference docs, and structured workflows that produce correct Contentful integrations on the first try.

Quickstart — Claude Code

Two commands. You get eight skills plus live MCP connections to your Contentful spaces.

/plugin marketplace add contentful/skills
/plugin install contentful@contentful

Run /reload-plugins to activate. This registers two MCP servers:

• contentful-mcp — connection to mcp.contentful.com for CMS operations
• contentful-personalization — local MCP for structured personalization workflows

---

What's inside

Skill	What it does
contentful-guide	Explains core concepts and routes you to the right skill, API, or doc. Start here.
contentful-api	Language-agnostic REST and GraphQL API reference — curl examples for CMA, CDA, CPA, Images, and GraphQL.
contentful-nextjs	Integrates Contentful into a Next.js project — SDK setup, content fetching, Draft Mode previews.
contentful-migration	Writes and runs content model migration scripts — fields, validations, transforms, editor interfaces.
contentful-env-analysis	Downloads an environment to a local SQLite snapshot and answers questions about content, references, Rich Text, and ExO entities. Read-only.
contentful-custom-app-from-scratch	Designs, scaffolds, builds, and validates new App Framework custom apps.
contentful-custom-app-enhancement	Improves and debugs existing Contentful custom apps in customer-owned repos.
contentful-personalization	Sets up, debugs, and develops personalization and A/B testing with the Experiences SDK.
channels-destinations	Sets up and manages Channels, Destinations, and Destination Nodes via the Destinations Management API.
exo-content-bindings	Creates Data Assemblies (content bindings) that connect entries to Experience Orchestration components.

The custom app skills are packaged together under skills/contentful-apps/.

---

Other platforms

Skills also work without the plugin on any platform that supports the agentskills.io spec.

Cursor

Install the Contentful Cursor plugin from Cursor Directory.

Alternatively, add the skills manually:

1. Open Settings → Rules
2. Click Add Rule → Remote Rule (GitHub)
3. Enter contentful/skills

Universal CLI

npx skills add contentful/skills

Works with GitHub Copilot, VS Code, OpenAI Codex, Gemini CLI, and 35+ other platforms.

More options

Gemini CLI:

gemini skills install contentful/skills

GitHub Copilot / VS Code:

Skills auto-discover from .agents/skills/ when added to your project. Use /skills in Copilot Chat to confirm they're loaded.

Install a single skill:

npx skills add contentful/skills --skill contentful-personalization

Available: contentful-guide, contentful-api, contentful-nextjs, contentful-migration, contentful-env-analysis, contentful-custom-app-from-scratch, contentful-custom-app-enhancement, contentful-personalization, channels-destinations

---

Skills

contentful-guide

Explains core Contentful concepts and routes you to the right skill or documentation. Start here if you're new to Contentful or unsure which API to use.

Triggers and details

Activates on: "Contentful 101", "which API should I use", "how do I get started", "what does X mean in Contentful"

Covers:

• Core vocabulary — spaces, environments, content types, entries, assets, locales
• API selection — CDA vs CPA vs CMA vs GraphQL vs Images API
• Routing to the right implementation skill
• Contentful MCP server orientation

contentful-api

Language-agnostic reference for Contentful's REST and GraphQL APIs. Pair this with any framework or language — examples are curl-based.

Triggers and details

Activates on: "curl Contentful", "CMA request", "CDA query parameters", "publish entry HTTP", "Images API URL", "Contentful GraphQL query"

Covers:

• Authentication — token types, headers, US/EU base URLs
• HTTP conventions — version locking, rate limits, pagination, error payloads, locale structure
• Content Management API — entries, content types, assets, environments, bulk actions
• Content Delivery API — querying, includes/link resolution, localization, sync
• Content Preview API — draft + published content via CDA endpoints
• Images API — on-the-fly transformations via URL parameters
• GraphQL Content API — querying with CDA tokens

contentful-nextjs

Add and configure Contentful in a Next.js project. Covers SDK setup, environment variables, content fetching, and Draft Mode preview flows for both App Router and Pages Router.

Triggers and details

Activates on: "add Contentful to Next.js", "Contentful SDK setup", "Draft Mode", "preview mode", "Server Components Contentful"

Covers:

• SDK installation and client configuration
• Environment variables and environment aliases
• Content fetching patterns (App Router and Pages Router)
• Draft Mode preview flows with CPA
• ISR (Incremental Static Regeneration) setup
• Troubleshooting common integration issues

contentful-migration

Write and run content model migration scripts using the Contentful migration library. Covers field operations, validations, entry transforms, and editor interface configuration.

Triggers and details

Activates on: "write a migration", "create content type", "schema migration", "field validation", "editor interface", "changeFieldId"

Covers:

• Content type creation, editing, and deletion
• Field operations — add, rename, move, change type
• Validations — range, regex, linked content types, asset file constraints
• Entry transforms — in-place edits, deriving linked entries, moving entries between types
• Editor interface wiring — widgets, field layout, sidebar controls
• Best practices — sandbox testing, sequential file naming, separating schema from data changes

contentful-custom-app-from-scratch

Design, scaffold, build, and validate a new Contentful App Framework custom app for your own repository or workspace.

Triggers and details

Activates on: "build a Contentful app", "custom app from scratch", "App Framework app", "sidebar app", "field editor app", "page app", "app action", "app function"

Covers:

• Idea shaping and v1 scoping for internal custom apps
• App location selection — app config, page, home, dialog, entry editor, entry field, entry sidebar
• Scaffolding with create-contentful-app
• App SDK, React Apps Toolkit, Forma 36, installation parameters, App Actions, and Functions guidance
• Local Contentful setup, sandbox testing, validation, and handoff

contentful-custom-app-enhancement

Improve, debug, and extend an existing Contentful App Framework custom app in a customer-owned repository.

Triggers and details

Activates on: "fix my Contentful app", "improve a custom app", "enhance App Framework app", "debug custom app", "update sidebar app", "custom app feature request"

Covers:

• Triage from bug reports, support notes, screenshots, and feature requests
• Existing app inspection across locations, SDK usage, parameters, App Actions, Functions, and backend code
• Small, reviewable implementation plans
• App-native UI and security guardrails
• Targeted tests, local smoke checks, sandbox verification, and PR handoff

contentful-env-analysis

Download a Contentful space and environment into a local SQLite snapshot, see inventory tables, and ask questions without changing remote content or starting an upgrade.

npx skills add contentful/skills --skill contentful-env-analysis

For reviewed-version installation and updates, follow the skill's security and data-handling guidance. The quick install above selects the current repository version; it is not integrity verification.

Restart your agent session, then invoke /contentful-env-analysis in Claude Code or $contentful-env-analysis in Codex. The agent creates .contentful-env-analysis/, asks you to configure credentials outside chat, shows the selected target and data-processing notice for confirmation, downloads the snapshot, and suggests questions.

Requires Node.js 24.21+, an AI agent with shell access, npm/npx and network access for installation, and a CMA token with read access for downloads. The installer may also need Git if its archive download is unavailable. Works with the same JavaScript bundle on Windows, macOS, and Linux. No Python, external SQLite, GitHub account, MCP server, or dependency installation is required. After downloading, script queries run offline; results supplied to an AI agent may be processed by its provider. Snapshot files contain customer content; keep them private and remove them when no longer needed.

Try asking:

• Which Rich Text fields are empty or contain Entry links?
• Which entries have no incoming links, and could they be page roots?
• Which content types have the most draft-only entries or missing translations?
• Which ExO Components and Experience Templates exist, and how many instances use each one?

contentful-personalization

Set up, debug, and develop with Contentful personalization and A/B testing. A structured, multi-step skill with three workflows and a reference library of 19+ documents.

Workflows and details

Activates on: "set up personalization", "A/B test", "personalization not working", "Experiences SDK", "run an experiment", "audience targeting"

Workflows:

• Onboard — Assess readiness, select SDK, guided installation, content type setup
• Doctor — Diagnose broken setups: checks packages, env vars, API connectivity, content state
• Develop — Day-to-day companion for personalizing components, running experiments, wiring analytics

Reference library: SDK guides, component patterns, SSR/middleware patterns, provider patterns, analytics setup, environment variables, error resolution, and more.

Built with @contentful/skill-kit — a structured state machine with MCP server integration.

channels-destinations

Set up and manage Channels, Destinations, and Destination Nodes through the Destinations Management API. Covers Channel contracts, Destination properties, Destination maps with experience/folder/redirect nodes, and safe publish, unpublish, and delete ordering.

Triggers and details

Activates on: "create a channel", "set up a destination", "destination map", "destination nodes", "assign an experience", "path routing", "publish a destination", "delete a destination"

Covers:

• Channel contracts — Destination properties, node properties, and the single Path property rule
• Building Destination maps with experience, folder, and redirect nodes
• Dependency-ordered publishing and leaf-first unpublish and deletion guardrails
• Verifying state after every write, and a "not executed" plan when no API integration is available

exo-content-bindings

Create Data Assemblies — the content-binding recipes that connect existing entries to Experience Orchestration component types. Covers classifying coded vs. composite components, judging content vs. design properties, public/private (hoisted) properties, and slot vs. content-binding scope, then designing, creating, linking, and publishing Data Assemblies via the CMA.

Triggers and details

Activates on: "create Data Assemblies", "content binding", "data assembly", "prebinding", "bind entries to components", "hydrate a component", "set up a Binding Set"

Covers:

• Space introspection and coded vs. composite component classification
• The content-property vs. design-property test, and the public/private hoisting rule
• Resolver patterns — entity, collection, nested Data Assembly, asset/Media fields, deep binding, polymorphic branching
• RichText handling, GraphQL query conventions, and the content-type-field-to-content-property type mapping
• A complete worked example, plus binding-set and DA-reuse guidance

---

MCP Server Setup

Plugin installs configure MCP connections automatically. If you installed via npx skills add or another non-plugin path, set up the MCP servers manually to get the full experience.

Contentful MCP (CMS operations)

Connects your agent to your Contentful spaces for reading and writing content, content types, and assets.

Claude Code:

/mcp add-http contentful-mcp https://mcp.contentful.com/mcp

Other platforms — add to your MCP config:

{
  "mcpServers": {
    "contentful-mcp": {
      "type": "http",
      "url": "https://mcp.contentful.com/mcp"
    }
  }
}

• Documentation: contentful.com/developers/docs/tools/mcp-server

Personalization MCP (structured workflows)

The contentful-personalization skill includes a local MCP server that powers its interactive workflows. Point your agent at the skill's run script:

Claude Code:

/mcp add -- /path/to/skills/contentful-personalization/scripts/run mcp --host claude-code

Other platforms — add to your MCP config:

{
  "mcpServers": {
    "contentful-personalization": {
      "command": "/path/to/skills/contentful-personalization/scripts/run",
      "args": ["mcp", "--host", "claude-code"]
    }
  }
}

Note

Replace /path/to/skills/ with the actual path where skills were installed (typically .agents/skills/ in your project).

---

Local Plugin Testing (Claude Code)

To test the full plugin locally — including skills, MCP servers, and hooks — without publishing:

claude --plugin-dir /path/to/contentful/skills

This loads everything defined in .claude-plugin/plugin.json for that session: skills, the Contentful MCP server, and the personalization MCP server. Use /reload-plugins inside the session to pick up changes without restarting.

You can also combine multiple plugin directories:

claude --plugin-dir ./skills --plugin-dir ./other-plugin

Contributing

See CONTRIBUTING.md for development setup and guidelines. We welcome bug reports, feature requests, and pull requests.

Help and Support

• Open a GitHub issue for bugs and feature requests
• For security issues, see SECURITY.md
• Contentful support: contentful.com/help

Contributors

François 💻

Tim Beyer 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT — see LICENSE for details.