---
name: nextjs-to-payload
description: "Add Payload CMS to an existing Next.js website. Use for App Router integration, content migration, draft preview, public access and cache behavior."
license: AGPL-3.0-or-later
compatibility: "Claude Code, Claude Cowork, ChatGPT Codex and Agent Skills hosts. Applying requires repository tools and a compatible Payload 3 server."
metadata:
  hive-tier: standalone
  paired-drone: none
  domain: payload-cms
  version: "1.0.0"
  research-observed: "2026-10-31"
---

# Next.js to Payload CMS

Add Payload-backed editorial content while preserving the target site's framework, layout, routes and branding. Produce reviewable integration changes, a migration ledger and evidence that anonymous readers cannot see drafts.

## When to use

Use when the owner asks to connect an existing Next.js website to Payload CMS, replace hardcoded articles with editable content, migrate an existing blog, or implement its draft preview and publication boundary.

## Boundaries

Read the target repository's instructions and installed package versions. Use this skill for the named framework only; use the sibling React, Next.js or Svelte skill when the detected framework differs. Content drafting belongs to Blog Content Stinger. WorkOS and MCP activation follow the included server's setup guide. No source brand, domain, identity, CMS ID or credential is a default for a consumer.

## Procedure

1. Read [README.md](README.md) and [the CMS contract](references/cms-contract.md). Inspect the existing routes, content sources, auth and deployment mode. Record exact versions and settle any architecture or storage decision before dependent edits.
2. Read [the research digest](references/research/distilled.md). Verify compatibility against current official documentation and the target lockfile. Pinned v3 examples do not promise compatibility with every release.
3. Follow [integration](guides/integrate.md). Implement one representative article end to end before applying the pattern broadly. Prepare dependency/configuration diffs for the owner's authorized scope.
4. Follow [migration](guides/migrate.md). Preserve URLs and content evidence, resolve media/author/tag IDs, and use an idempotent import with a dry-run result before an authorized application.
5. Follow [verification](guides/verify.md). Run existing project checks and the ledger validator. Test public published content, never-published drafts, changed drafts, authenticated preview and machine publication denial.
6. Deliver the changed files, exact commands/results, migration state, rollback path and unresolved limitations. Obtain approval before live writes, installs, cutover, deployment, publication or Git operations that require it.

## References

- [CMS contract](references/cms-contract.md): inputs, content shape and auth boundaries.
- [Research digest](references/research/distilled.md): official sources, version conflict and grounding sample.
- [Migration ledger](templates/migration-ledger.json): local import/reconciliation record.
- [Posts collection fragment](templates/Posts.ts): trusted-editor scaffold; configure related collections and the machine writer policy before use.
- [Ledger validator](scripts/validate-migration.py): run with a local ledger path; performs no writes or network calls.

## Critical Directive

- You must read all files and context contained within your skill.
- In the event your core knowledge does not provide sufficient guidance you must make every attempt to search the internet, related knowledge base documentation files, and other available resources to supplement your knowledge prior to proceeding with your task.
- Additional related skills can be found here:
  - [React to Payload](../react-to-payload/SKILL.md) - React/Vite integration.
  - [Next.js to Payload](../nextjs-to-payload/SKILL.md) - Next.js integration.
  - [Svelte to Payload](../svelte-to-payload/SKILL.md) - Svelte/SvelteKit integration.

## Domain-change handoff

Read [the shared domain-change control](../../references/domain-change-control.md) before any domain, DNS, custom-domain or ownership-verification work. The user personally clicks the final Save or equivalent committing action. Do not bypass that handoff with an API, script, automatic provider connection, Enter or an autosaving form. Inspect fresh state after the user acts.

## Ship Gate

Prior to committing any code to the repository you must utilize in order the security-stinger, quality-stinger, and github-repo-health-stinger. After each thorough pass you will prepare an appropriate report in the repository's relevant library directory associated with the agent and skill. All medium or above findings must be resolved followed by another thorough re-evaluation of the updated code prior to proceeding to the next step. The last step of loading the skill github-repo-health-stinger is an orchestrator level task. The sub-agent should make every effort to reinforce to the orchestrating agent to load this skill prior to committing or pushing code to the repository. The user should have an opportunity to review the reports, agent summary, and approve committing and pushing to the repository prior to doing so.