关于 payloadcms
payloadcms 是用于处理 Payload 项目的 Agent 技能，指导项目初始化、模型变更、故障排查和发布准备，并包含验证与回滚检查。
主要功能
- 01初始化 Payload 项目
- 02建模集合与全局配置
- 03排查管理界面和 API 问题
- 04规划迁移与回滚
- 05验证生产变更
适用场景
- 01在 Next.js 应用中加入 Payload
- 02安全修改集合字段
- 03诊断管理页面故障
- 04准备生产环境发布
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/payloadcms确认已加载。
附带文件evals/evals.jsonSKILL.toon
详细介绍
payloadcms — Payload CMS 运维指南
关键词：
payload、payloadcms、headless cms、payload config
何时使用此技能
- 设置新的 Payload 项目（或将 Payload 添加到现有的 Next.js 应用中）
- 定义或演进集合、全局配置、访问控制和字段架构
- 在本地运行/开发/测试 Payload，并验证管理界面/API 的行为
- 规划安全的内容模型迁移和回滚策略
- 准备可用于生产环境的 Payload 变更，并制定明确的验证检查
何时不使用此技能
- 不涉及 Payload 运行时的通用 API 契约工作 → 使用
api-design - Payload 专属设置以外的身份验证架构决策 → 使用
authentication-setup - 不受 Payload 模型约束的纯数据库物理架构调优 → 使用
database-schema-design - 不针对 Payload 运行时的广泛部署编排 → 使用
deployment-automation
说明
步骤 1）确定操作模式
在编辑任何内容之前，选择一个主要模式：
| 模式 | 适用情况 | 核心产出 |
|---|---|---|
| 引导搭建 | 全新安装或首次集成 | 可运行的本地 Payload 应用 |
| 建模 | 更新集合/全局配置架构 | 经过审查的模型差异 + 迁移说明 |
| 运行时调试 | 管理界面/API 故障或配置错误 | 根本原因 + 已验证的修复方案 |
| 发布准备 | 生产环境发布请求 | 风险/回滚 + 验证清单 |
步骤 2）发布前检查
- 验证仓库中的运行时/工具链（
node、包管理器、框架布局） - 找到 Payload 配置（
payload.config.*）和模型文件 - 确认环境变量/密钥的配置情况（
DATABASE_URI、存储/身份验证密钥） - 在修改架构前检查现有迁移历史
步骤 3）执行最小可行工作流
A. 引导搭建
- 根据仓库的包管理器安装依赖
- 使用所需的最少集合生成/初始化 Payload 配置
- 运行本地开发环境并验证以下两项：
- 管理界面正常加载
- 至少一个集合的 API 能够响应
B. 建模
- 每次只进行一项范围明确的模型变更（添加/删除/更改字段类型）
- 记录影响范围：受影响的集合、API 输出、管理表单、种子数据/导入任务
- 在合并前准备迁移路径和回滚路径
C. 运行时调试
- 在本地或预发布环境中，通过具体故障端点/页面复现问题
- 检查配置、环境变量绑定、访问规则和适配器连接
- 通过明确的前后对比证据（端点 + 管理界面行为）验证修复
D. 发布准备
- 确认迁移顺序和停机时间假设
- 添加回滚说明（回退迁移、恢复备份、在使用功能标志时禁用它们）
- 确保验证清单可在 CI 或预发布环境的冒烟测试中执行
步骤 4）验证清单
- Payload 服务启动时没有架构/运行时错误
- 至少通过 API 和管理界面验证一个已修改的集合/全局配置
- 迁移步骤可确定且可逆
- 面向生产环境的变更附有风险和回滚说明
示例
示例 1：安全地添加新集合
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
示例 2：调试故障的管理面板路由
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
最佳实践
- 每个 PR 中的模型变更应保持小范围且可审查
- 没有迁移和回滚说明时，绝不合并架构变更
- 对涉及的模型同时验证管理界面和 API
- 优先使用明确的访问规则，而非隐式默认值
- 将环境变量绑定和适配器配置视为首要检查项
参考资料
- Payload 仓库：https://github.com/payloadcms/payload
- Payload 文档：https://payloadcms.com/docs/getting-started/what-is-payload
- 调研证据记录：
.survey/hourly-skill-candidates-20260427-095216/evidence.json
评论
支持 Markdown