agentleFS
textura-agencytextura-agency/next16-claude-starter/.claude/skills/payload-cms/SKILL.md

payload-cms

Skill141 starsChanged 34 days agoUnlicenseView on GitHub

Put a Payload CMS admin on a site built from this starter — every visible string and content photo editable, derived from the site's own content objects with the code's copy as the fallback, a per-page SEO global that drives <head>/JSON-LD/sitemap/llms.txt, Supabase Postgres + Storage, migrations only, static routes revalidated on save. Ships copy-ready kits (core, admin skin, analytics, editor's guide, legal rich text, a blog, and many data-driven pages with a quality bar for indexing) proven on a production site. Use when the user asks to "add a CMS / admin / Payload", "make the content editable", "let the client edit the text", "SEO in the admin", "add a blog / articles / news", "location pages", "programmatic SEO", "a page per service / city / integration", or wants marketing copy out of hardcoded props. For the admin's look and the editor's guide see `payload-admin`; for visitor analytics see `payload-analytics`.

  • Reads credentials
  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every one of these was a request or a defect on the reference site.

    line 21
  2. Very specific:

    Every route's metadata comes through its view (hard rule #5 — page.tsx imports only @/views): the view exports export const getHomeMetadata …

    line 141
  3. Very specific:

    Keep the starter's route registry (src/lib/routes.ts): one SEO_PAGES entry per ROUTES entry, same paths.

    line 151
  4. Very specific:

    Commit src/payload-types.ts, src/migrations/*, importMap.js.

    line 168

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Payload CMS — the admin flow

This is the flow a production site went through to get an admin its owner called "great": every word on the site editable, grouped the way the site reads, SEO per page with a live link preview, light consented analytics, the site's own look, and a guide with screenshots inside the admin. It is written down as kits (templates/) and decisions (below) so the next site gets there in one pass instead of twenty requests.

Read first: obsidian/workflows/cms-admin.md (the flow at a glance) and obsidian/backend/cms-payload.md (the architecture). Verified against Payload 3.89 · Next 16.3 · Node 24 (2026-10).

The decisions — and why

Every one of these was a request or a defect on the reference site. Don't undo one without the reason in front of you.

#DecisionWhy
D1Payload inside the app — app/(payload) + app/(site), one build, one deployThe owner asked for one project. Local API reads in process — no HTTP hop, works at build time.
D2Fields are derived from the content objects (text-schema.ts walks src/data/mocks/*), not hand-writtenEvery string becomes a field defaulted to today's copy; a new line in code is a new field next deploy. Hand-written schemas drift and miss copy.
D3Reading is a merge: getText("hero") returns the code's HERO with the admin's strings laid over it — same typeViews and components stay untouched. A deliberate exception to "use the generated type in the view" (rule payload.md).
D4Blank / missing / DB down → the code's copy, error loggedThe site never goes blank because the CMS did. A fresh database renders the full site.
D5Globals, not collections or blocks, for a marketing page's sectionsEach section exists once; its order is choreographed with motion/scene, so it is not the editor's to reorder. Collections only for things that are many (posts, cases). Blocks only when the editor genuinely composes pages.
D6Wiring is skipped (SKIP: id, href, anchors, textures, scene data…); card lists have fixed rows matched by a hidden keyThe editor rewrites a card but cannot break the layout, cross-wire a card to another's image, or add a 7th card to a 6-slot ring.
D7OPEN_LISTS with a floor/ceiling for lists the layout can resize; an added row must fill every line + photoThe client asked to change counts; the floor is what keeps a carousel from showing empty glass.
D8Photos are optional uploads beside their copy ("Replace photo"): blank → photo in code; upload → its URL, alt, a 512 px small size for textures, crop droppedSame fallback rule as text. Only content photos — decorative art and the scene stay in code.
D9One SEO global, a tab per page + Site defaults; parity with everything <head>, JSON-LD and sitemap.xml emit; a link-preview card per tab"SEO for each page, the same as the site has it." Titles are absolute (Brand | …, 50–60 chars) and written for search; the plugin's fields are placed by hand because routes are fixed.
D10Share image seeded into Media on onInit (idempotent, never throws)The editor sees the real card in the admin and can replace it, instead of a hint about a file in the code.
D11Routes stay static; every global's afterChange → revalidatePath("/", "layout")Hard rule #15 holds; saves still show at once.
D12Migrations only, push: false everywhere; yarn migrate:direct over the session poolerThe same steps on every machine and the host. push against a live DB is how schemas get rewritten.
D13Storage plugin always registered (enabled from env, alwaysInsertFields), files linked from the public bucket URLThe schema — and so the migrations — never depend on whether a laptop has S3 keys. next/image and WebGL loaders fetch from Supabase's CDN, not through /api/media/file.
D14English admin, labels in the editor's words, sidebar groups in reading order, row labels from the row's own copyAn admin that reads like the site is one an owner uses.
D15Every legal section is one rich-text field (bold, links, lists, h3; table/button as blocks)Asked for after a block-per-paragraph model: an editor could not bold a word or link inside a sentence. Start with rich text.
D16/admin and /api/ disallowed in robots.ts; /llms.txt from the SEO global; sitemap lastmod = the globals' updatedAtSEO audit findings: a login screen in the crawl budget, request-time lastmod (ignored), no llms.txt.
D17Things that are many (posts, locations, services) are collections with their own routes — the blog / collection kits — each page indexed only when it clears a bar, an old slug answering 308Blogs and page sets are where sites win long-tail search, and where thin, templated or orphaned pages lose it.

The kits

bash .claude/skills/payload-cms/scaffold.sh <kit…> copies a kit into the project (never overwrites without --force) and prints every file — that list is your checklist. Then grep -rn 'TODO\|PROJECT CONFIG' src/cms src/app and fill each one.

KitFilesSkill
corepayload.config.ts, (payload)/* plumbing, (site)/layout.tsx, global-not-found.tsx, layouts/site-document.tsx, cms/{text-schema,content,globals,seo,seo-pages,seed}.ts, collections users/media, admin/share-preview.tsx, llms.txt/route.ts, scripts/migrate-direct.mjsthis one
admin(payload)/custom.css (the skin), admin/{graphics,welcome,row-label}.tsxpayload-admin
analyticscms/analytics.ts, collections/page-views.ts, api/track/route.ts, analytics-beacon.tsx, admin/analytics-*.tsx, admin/format.tspayload-analytics
guideadmin/guide-{content,body,view,nav}.tsx (+ yarn qa:shots)payload-admin
legalcms/legal*.ts, views/legal/legal-rich-text.tsx — adapt-kit (--force)references/legal-rich-text.md
blogcollections posts / topics / authors, cms/blog.ts, views/blog/*, (site)/blog/{page,[slug],topic/[slug],author/[slug],feed.xml}references/blog.md
collectioncollection entries + cms/entries{,-config}.ts, views/entries/*, (site)/entries/{page,[slug]} — renamed per project (locations, services…)references/collection-pages.md

blog and collection bring cms-shared (slug + previous-slug redirects, the Search & sharing fields, the Lexical renderer with <h2> anchors and next/image, visible breadcrumbs, guarded reads). Each kit adds its hub to ROUTES + SEO_PAGES, its entries to sitemap.ts and /llms.txt — the reference's checklist.

core + admin is the minimum (the (payload) layout imports the skin). payload.config.ts marks each kit's lines — delete the ones not installed.

Phase 0 — Pre-flight (stop if any fails)

  1. Node ≥ 22 (24 recommended), pinned in .nvmrc. On Node 20.17 Payload's CLI (generate:importmap, generate:types, migrate:*) exits 0 and does nothing — no error, no file. node -v before every CLI call.
  2. Next vs Payload peers: npm view @payloadcms/next@<ver> peerDependencies against package.json's next. Pin all @payloadcms/* and payload to the same exact version (no caret).
  3. A Supabase project with its connection strings — run supabase-db first if not. Details: references/supabase-wiring.md.
  4. All copy lives in typed objects in src/data/mocks/. Derivation (D2) only sees what is there. Sweep src/views and src/components for literal copy (headings, buttons, form errors, cookie banner, menu, emails in lib/, 404, legal labels) and move it into mocks before installing — this is the step the reference site had to redo twice. aria-labels may stay in code.
  5. Propose the admin to the user before writing config: the sidebar (Home page → numbered sections in scroll order, Site → header/footer/forms/ emails/cookie banner/SEO, Pages & documents → 404 + legal, Settings), what stays in code, which lists are open and why, which kits. Get a yes.

Phase 1 — Install and split

yarn add payload@<v> @payloadcms/next@<v> @payloadcms/db-postgres@<v> \
  @payloadcms/richtext-lexical@<v> @payloadcms/storage-s3@<v> \
  @payloadcms/plugin-seo@<v> @payloadcms/translations@<v> graphql sharp
bash .claude/skills/payload-cms/scaffold.sh core admin
  • package.json: "type": "module"; scripts payload, generate:types, generate:importmap, migrate, migrate:create, "migrate:direct": "node scripts/migrate-direct.mjs".
  • tsconfig.json paths: "@payload-config": ["./src/payload.config.ts"].
  • next.config.ts: export default withPayload(nextConfig), experimental.globalNotFound: true, and images.remotePatterns for *.supabase.co + *.storage.supabase.co at /storage/v1/object/public/**.
  • src/env.ts + .env.example — references/supabase-wiring.md §Env (all optional strings, empty = unset, so a laptop without a DB still builds).
  • Split the app into two root layouts: git mv src/app/{page.tsx, error.tsx,not-found.tsx,privacy-policy,robot-view,…} → src/app/(site)/; move the body of the old app/layout.tsx into src/layouts/site-document.tsx (the kit's copy is the starter's layout as shipped — merge, don't overwrite) and delete app/layout.tsx. api/, robots.ts, sitemap.ts, manifest.ts, globals.css stay at app/. Point global-not-found.tsx at the real 404 view.
  • verify.sh already skips src/payload-types.ts and src/app/(payload)/.

Phase 2 — The content model

In text-schema.ts and globals.ts (references/content-model.md has the rules and the edge cases):

  1. TEXT_GLOBALS — one entry per content object, slug / numbered label / group / base / a one-line note (what the screen is + any rule before Save). Group order = sidebar order.
  2. SKIP — every wiring key the mocks use. Read each mock; anything a reader never sees as words.
  3. OPEN_LISTS / FIXED_LISTS — with the reason in a comment, from the component's real constraints (a ring's angle, a marquee's fill, a headline's line count).
  4. LABELS — every key whose humanised name an editor wouldn't understand.
  5. Views read through content.ts: const hero = await getText("hero") in the view (Server Component), passed down exactly as the mock was. Nothing below the view changes. Shared chrome (header, footer, cookie banner) is read once in SiteDocument / the layout and passed as props.
  6. Emails and other server copy: getText("emails") in the route; placeholders are named ({name}, {company}) and the editor's text is escaped.

Phase 3 — SEO (part of core — never skip)

  1. seo-pages.ts: one entry per route + the 404 — titles 50–60 chars, absolute, opening on the brand; descriptions 100–150; written for search.
  2. Every route's metadata comes through its view (hard rule #5 — page.tsx imports only @/views): the view exports export const getHomeMetadata = () => getPageMetadata("home") and the page does export const generateMetadata = getHomeMetadata. (site)/layout.tsx uses getSiteMetadata(); SiteDocument renders getStructuredData().
  3. sitemap.ts → getSitemapPages() (noindex pages dropped, lastmod from the content). robots.ts → add /admin and /api/ to NEVER_CRAWLED (keep /robot-view and the starter's per-purpose AI-crawler groups).
  4. /llms.txt from the kit — it replaces the starter's src/app/llms.txt/route.ts. Details: references/seo-global.md.
  5. Keep the starter's route registry (src/lib/routes.ts): one SEO_PAGES entry per ROUTES entry, same paths. Collection pages (blog, collection kits) are not registry entries — their hub is; the kit's get…Sitemap() / get…LlmsLines() add the rest. verify.sh still FAILs on a page missing from ROUTES, and the breadcrumb JSON-LD reads its parent chain.

Phase 4 — Schema, migration, first user

node -v                                   # ≥ 22 — see Phase 0
yarn generate:importmap                   # silent no-op? → node node_modules/payload/bin.js generate:importmap --force
yarn generate:types
yarn migrate:direct create init           # bare migrate:create does not load .env.local
yarn migrate:direct                       # apply over the session pooler
yarn dev                                  # /admin → create the first user

Commit src/payload-types.ts, src/migrations/*, importMap.js. A rename the drizzle prompt would ask about cannot be answered non-interactively — split it into drop + add migrations, or hand-write it and patch the .json snapshot (references/supabase-wiring.md §Migrations).

Phase 5 — The admin's look → payload-admin skill (§Skin)

Phase 6 — Analytics (only if wanted) → payload-analytics skill

Phase 7 — The editor's guide → payload-admin skill (§Guide) — last, it documents the final admin

Phase 8 — Prove it (each one, not "it built")

  1. Edit → site: change a field in each group, Save, refresh the site — shown. Put it back.
  2. Blank → fallback: clear a field — the code's copy shows, nothing breaks.
  3. No database: unset DATABASE_URL, yarn build && yarn start — the full site renders from code, errors logged once per global.
  4. Photo: upload into a "Replace photo" field — the file lands in the bucket, the site shows it via the public URL; delete it → the code's photo returns.
  5. Open list: cut to the floor and add a row — the section still looks right at rest and in motion; a half-filled new row is refused with its missing lines.
  6. SEO: view-source on each route — title, description, canonical, og:image (1200 × 630), JSON-LD; sitemap.xml, robots.txt, /llms.txt.
  7. Static: the build output lists the site's routes as static (○), not ƒ.
  8. yarn verify · yarn lint · yarn build · Lighthouse unchanged (yarn qa:lh) — the CMS must not cost the site a point.

Phase 9 — Vault (same turn)

cms-payload.md (what this project's admin holds: groups, open lists, kits, where data lives), tech-stack.md + changelog.md (deps), environment- variables.md, an ADR for any departure from D1–D17.

Traps (each cost time on the reference site)

  • Payload CLI on Node 20.17 → silent no-op (Phase 0).
  • Payload CLI without "type": "module" in package.json → ERR_REQUIRE_ASYNC_MODULE from @payloadcms/richtext-lexical (Phase 1).
  • .env.local overrides .env — a DATABASE_URL left in both takes .env.local's.
  • Password with %/$ in the URL: % throws "URI malformed"; $ is expanded by @next/env and silently shortens it. Percent-encode, or letters+digits.
  • Supabase's Direct host is IPv6-only → ENOTFOUND on IPv4; use the session pooler (5432) for DATABASE_URL_DIRECT.
  • revalidatePath throws outside a request (seed, script) — the kit catches it.
  • A "use client" module's exports are client references — a server component can't call a helper exported from one (why admin/format.ts exists).
  • Payload's rich-text types use any — verify.sh skips payload-types.ts, and eslint.config.mjs ignores it, src/migrations/ and importMap.js.
  • Payload's admin class names aren't a public API: after an upgrade, open /admin and re-check the skin.
  • Saving locally writes the live DB when dev and prod share one Supabase project — say so to the user; test edits go in and come back out.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.