payloadcms

name: payloadcms description: > Operate Payload CMS (Next.js-native headless CMS) in repo workflows: bootstrap a Payload app, configure collections/globals, run local dev + migrations, and ship safe content-model changes. Use when the request mentions Payload CMS, payload config, collection schema, admin panel, or Next.js + headless CMS integration. allowed-tools: Bash Read Write Edit Glob Grep WebFetch metadata: tags: payloadcms,payload,cms,headless-cms,nextjs,backend,content-model,migration version: "1.0" source: https://github.com/payloadcms/payload license: MIT

payloadcms — Payload CMS operator

Keyword: payload, payloadcms, headless cms, payload config

When to use this skill

• Set up a new Payload project (or add Payload into an existing Next.js app)
• Define or evolve collections, globals, access control, and field schemas
• Run/dev/test Payload locally and verify admin/API behavior
• Plan safe content-model migrations and rollback strategy
• Prepare production-ready Payload changes with explicit validation checks

When not to use this skill

• Generic API contract work with no Payload runtime context → use api-design
• Auth architecture decisions outside Payload-specific setup → use authentication-setup
• Pure DB physical schema tuning without Payload model constraints → use database-schema-design
• Broad deployment orchestration not specific to Payload runtime → use deployment-automation

Instructions

Step 1) Identify the operating mode

Pick one primary mode before editing anything:

Step 2) Preflight checks

1. Verify runtime/toolchain in repo (node, package manager, framework layout)
2. Locate Payload config (payload.config.*) and model files
3. Confirm environment/secrets shape (DATABASE_URI, storage/auth keys)
4. Inspect existing migration history before schema edits

Step 3) Execute smallest valid workflow

A. Bootstrap

• Install dependencies according to repo package manager
• Generate/init Payload configuration with minimal required collections
• Run local dev and verify both:
  • Admin UI loads
  • API responds for at least one collection

B. Modeling

• Edit one bounded model change at a time (field add/remove/type changes)
• Document blast radius: affected collections, API output, admin forms, seed/import jobs
• Prepare migration path and rollback path before merge

C. Runtime debug

• Reproduce in local or staging with concrete failing endpoint/page
• Check config, env bindings, access rules, and adapter wiring
• Verify fix with explicit before/after proof (endpoint + admin behavior)

D. Release prep

• Confirm migration order and downtime assumptions
• Add rollback notes (revert migration, restore backup, disable feature flags if used)
• Ensure verification list is executable in CI or staging smoke tests

Step 4) Validation checklist

• Payload server starts without schema/runtime errors
• At least one modified collection/global is verified through API and admin
• Migration steps are deterministic and reversible
• Risk + rollback notes are present for production-bound changes

Examples

Example 1: Add a new collection safely

Prompt: "Add a blog-post collection to our Payload app and keep migration risk low"

Mode:
- Modeling

Expected flow:
- Locate payload config and collection directory
- Add collection schema with access defaults
- Run local checks (admin + API)
- Document migration/rollback in PR notes

Example 2: Debug broken admin panel route

Prompt: "Payload admin page fails after yesterday's schema change"

Mode:
- Runtime debug

Expected flow:
- Reproduce failure
- Isolate misconfigured field/access/env issue
- Apply minimal fix
- Verify admin loads and affected API endpoint works

Best practices

1. Keep model changes small and auditable per PR
2. Never merge schema changes without migration + rollback notes
3. Validate both admin UI and API surface for touched models
4. Prefer explicit access rules over implicit defaults
5. Treat environment binding and adapter configuration as first-class checks

References

• Payload repo: https://github.com/payloadcms/payload
• Payload docs: https://payloadcms.com/docs/getting-started/what-is-payload
• Survey evidence run: .survey/hourly-skill-candidates-20260427-095216/evidence.json