payload — Claude Code skill: what it does, how to install
Guides Payload CMS development across collections, hooks, and access control. Useful when debugging queries, validation, and database transactions.
npx skills add payloadcms/skills --skill payload -a claude-codeWhat payload does
This skill guides coding assistants through Payload CMS architecture in Next.js and TypeScript. It covers payload.config.ts configuration, field declarations, row-level access control, and the Local API.
Inside, it outlines patterns for collections and fields: draft workflows with versions: { drafts: true }, virtual fields using field-level hooks.afterRead, and conditional fields via admin.condition. Transactions require threading req through every operation, otherwise database state can desynchronize. To avoid infinite loops inside hooks, check req.context.
It also details background task queues, geospatial queries with point fields, and plugin creation using SWC compilation.
What it helps with
- configure row-level access control with query filters
- stop infinite hook loops by checking
req.context - enable drafts and versioning in collection configs
- thread
reqacross operations for transaction integrity
Example prompts for the agent
- How do I configure draft workflows in payload.config.ts?
- Show me how to stop afterChange hooks from looping during Next.js revalidation.
- Write a beforeDelete hook to cascade document deletions.
How to install payload
1Skills CLI (Vercel)
npx skills add payloadcms/skills --skill payload -a claude-code2Manually: put the files in place
~/.claude/skills/payload/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/payload/
1Skills CLI (Vercel)
npx skills add payloadcms/skills --skill payload -a codex2Manually: put the files in place
.agents/skills/payload/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add payloadcms/skills --skill payload -a cursor2Manually: put the files in place
.cursor/skills/payload/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install payloadcms/skills payload2Manually: put the files in place
.github/skills/payload/SKILL.md1Skills CLI (Vercel)
npx skills add payloadcms/skills --skill payload -a gemini-cli2Platform CLI
gemini skills install https://github.com/payloadcms/skills --path skills/payloadManually: put the files in place
.devin/skills/payload/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add payloadcms/skills --skill payload -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about payload
How to install payload in Claude Code?
Run npx skills add payloadcms/skills --skill payload -a claude-code to install the skill.
What does the payload skill do?
It provides patterns and rules for building Payload CMS applications in Next.js. It assists with collection schemas, relationship queries, access rules, and hook lifecycle debugging.
How does the skill handle database transactions?
It enforces passing the req object through all operations. This threads the active transaction context directly to database adapters.
