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
- Firzus/agent-skillstheir own version, first seen Oct 23, 2026
- monomango-jamie/claude-skillstheir own version, first seen Apr 21, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- Firzus/agent-skills★ 4same name
- monomango-jamie/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- aeo-visibilitySkill
- figma-to-sectionSkill
- i18n-seoSkill
- local-seoSkill
- mobile-device-qaSkill
- optimize-3d-sceneSkill
- optimize-loadSkill
- optimize-performanceSkill
- payload-adminSkill
- payload-analyticsSkill
- qa-verifySkill
- schema-markupSkill
- seo-auditSkill
- seo-growSkill
- ship-checkSkill
- site-migrationSkill
- supabase-authSkill
- supabase-dbSkill
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
- Distinctive: line 21
Every one of these was a request or a defect on the reference site.
- Very specific: line 141
Every route's metadata comes through its view (hard rule #5 — page.tsx imports only @/views): the view exports export const getHomeMetadata …
- Very specific: line 151
Keep the starter's route registry (src/lib/routes.ts): one SEO_PAGES entry per ROUTES entry, same paths.
- Very specific: line 168
Commit src/payload-types.ts, src/migrations/*, importMap.js.
≈ “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.
Files
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.
| # | Decision | Why |
| D1 | Payload inside the app — app/(payload) + app/(site), one build, one deploy | The owner asked for one project. Local API reads in process — no HTTP hop, works at build time. |
| D2 | Fields are derived from the content objects (text-schema.ts walks src/data/mocks/*), not hand-written | Every 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. |
| D3 | Reading is a merge: getText("hero") returns the code's HERO with the admin's strings laid over it — same type | Views and components stay untouched. A deliberate exception to "use the generated type in the view" (rule payload.md). |
| D4 | Blank / missing / DB down → the code's copy, error logged | The site never goes blank because the CMS did. A fresh database renders the full site. |
| D5 | Globals, not collections or blocks, for a marketing page's sections | Each 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. |
| D6 | Wiring is skipped (SKIP: id, href, anchors, textures, scene data…); card lists have fixed rows matched by a hidden key | The 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. |
| D7 | OPEN_LISTS with a floor/ceiling for lists the layout can resize; an added row must fill every line + photo | The client asked to change counts; the floor is what keeps a carousel from showing empty glass. |
| D8 | Photos are optional uploads beside their copy ("Replace photo"): blank → photo in code; upload → its URL, alt, a 512 px small size for textures, crop dropped | Same fallback rule as text. Only content photos — decorative art and the scene stay in code. |
| D9 | One 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. |
| D10 | Share 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. |
| D11 | Routes stay static; every global's afterChange → revalidatePath("/", "layout") | Hard rule #15 holds; saves still show at once. |
| D12 | Migrations only, push: false everywhere; yarn migrate:direct over the session pooler | The same steps on every machine and the host. push against a live DB is how schemas get rewritten. |
| D13 | Storage plugin always registered (enabled from env, alwaysInsertFields), files linked from the public bucket URL | The 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. |
| D14 | English admin, labels in the editor's words, sidebar groups in reading order, row labels from the row's own copy | An admin that reads like the site is one an owner uses. |
| D15 | Every 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' updatedAt | SEO audit findings: a login screen in the crawl budget, request-time lastmod (ignored), no llms.txt. |
| D17 | Things 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 308 | Blogs 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.
| Kit | Files | Skill |
core | payload.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.mjs | this one |
admin | (payload)/custom.css (the skin), admin/{graphics,welcome,row-label}.tsx | payload-admin |
analytics | cms/analytics.ts, collections/page-views.ts, api/track/route.ts, analytics-beacon.tsx, admin/analytics-*.tsx, admin/format.ts | payload-analytics |
guide | admin/guide-{content,body,view,nav}.tsx (+ yarn qa:shots) | payload-admin |
legal | cms/legal*.ts, views/legal/legal-rich-text.tsx — adapt-kit (--force) | references/legal-rich-text.md |
blog | collections posts / topics / authors, cms/blog.ts, views/blog/*, (site)/blog/{page,[slug],topic/[slug],author/[slug],feed.xml} | references/blog.md |
collection | collection 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)
- 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 -vbefore every CLI call. - Next vs Payload peers:
npm view @payloadcms/next@<ver> peerDependenciesagainstpackage.json'snext. Pin all@payloadcms/*andpayloadto the same exact version (no caret). - A Supabase project with its connection strings — run
supabase-dbfirst if not. Details:references/supabase-wiring.md. - All copy lives in typed objects in
src/data/mocks/. Derivation (D2) only sees what is there. Sweepsrc/viewsandsrc/componentsfor literal copy (headings, buttons, form errors, cookie banner, menu, emails inlib/, 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. - 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 adminpackage.json:"type": "module"; scriptspayload,generate:types,generate:importmap,migrate,migrate:create,"migrate:direct": "node scripts/migrate-direct.mjs".tsconfig.jsonpaths:"@payload-config": ["./src/payload.config.ts"].next.config.ts:export default withPayload(nextConfig),experimental.globalNotFound: true, andimages.remotePatternsfor*.supabase.co+*.storage.supabase.coat/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 mvsrc/app/{page.tsx, error.tsx,not-found.tsx,privacy-policy,robot-view,…}→src/app/(site)/; move the body of the oldapp/layout.tsxintosrc/layouts/site-document.tsx(the kit's copy is the starter's layout as shipped — merge, don't overwrite) and deleteapp/layout.tsx.api/,robots.ts,sitemap.ts,manifest.ts,globals.cssstay atapp/. Pointglobal-not-found.tsxat the real 404 view. verify.shalready skipssrc/payload-types.tsandsrc/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):
TEXT_GLOBALS— one entry per content object, slug / numbered label / group /base/ a one-linenote(what the screen is + any rule before Save). Group order = sidebar order.SKIP— every wiring key the mocks use. Read each mock; anything a reader never sees as words.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).LABELS— every key whose humanised name an editor wouldn't understand.- 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 inSiteDocument/ the layout and passed as props. - 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)
seo-pages.ts: one entry per route + the 404 — titles 50–60 chars, absolute, opening on the brand; descriptions 100–150; written for search.- Every route's metadata comes through its view (hard rule #5 —
page.tsximports only@/views): the view exportsexport const getHomeMetadata = () => getPageMetadata("home")and the page doesexport const generateMetadata = getHomeMetadata.(site)/layout.tsxusesgetSiteMetadata();SiteDocumentrendersgetStructuredData(). sitemap.ts→getSitemapPages()(noindex pages dropped,lastmodfrom the content).robots.ts→ add/adminand/api/toNEVER_CRAWLED(keep/robot-viewand the starter's per-purpose AI-crawler groups)./llms.txtfrom the kit — it replaces the starter'ssrc/app/llms.txt/route.ts. Details:references/seo-global.md.- Keep the starter's route registry (
src/lib/routes.ts): oneSEO_PAGESentry perROUTESentry, same paths. Collection pages (blog,collectionkits) are not registry entries — their hub is; the kit'sget…Sitemap()/get…LlmsLines()add the rest.verify.shstill FAILs on a page missing fromROUTES, and the breadcrumb JSON-LD reads itsparentchain.
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 userCommit 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")
- Edit → site: change a field in each group, Save, refresh the site — shown. Put it back.
- Blank → fallback: clear a field — the code's copy shows, nothing breaks.
- No database: unset
DATABASE_URL,yarn build && yarn start— the full site renders from code, errors logged once per global. - 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.
- 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.
- SEO: view-source on each route — title, description, canonical, og:image
(1200 × 630), JSON-LD;
sitemap.xml,robots.txt,/llms.txt. - Static: the build output lists the site's routes as static (○), not ƒ.
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"inpackage.json→ERR_REQUIRE_ASYNC_MODULEfrom@payloadcms/richtext-lexical(Phase 1). .env.localoverrides.env— aDATABASE_URLleft in both takes.env.local's.- Password with
%/$in the URL:%throws "URI malformed";$is expanded by@next/envand silently shortens it. Percent-encode, or letters+digits. - Supabase's Direct host is IPv6-only →
ENOTFOUNDon IPv4; use the session pooler (5432) forDATABASE_URL_DIRECT. revalidatePaththrows 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 (whyadmin/format.tsexists). - Payload's rich-text types use
any—verify.shskipspayload-types.ts, andeslint.config.mjsignores it,src/migrations/andimportMap.js. - Payload's admin class names aren't a public API: after an upgrade, open
/adminand 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.
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
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.

