feat(cpa): add --agent flag for coding agent skill installation (#16278)

# Overview

Replace hard-coded `.cursor/rules` and `AGENTS.md` files in templates
with a dynamic `--agent` flag in `create-payload-app`. When a user
selects a coding agent during project creation, the Payload skill
(`SKILL.md` + `reference/` docs) is downloaded from GitHub and placed in
the correct directory for that agent. A `CLAUDE.md` or `AGENTS.md` is
written at the project root to point the agent to the skill.

Supports `claude`, `codex`, `cursor` initially.

<img width="514" height="386" alt="image"
src="https://github.com/user-attachments/assets/c5bc9e68-0c02-4881-ae6c-957e465e9f96"
/>


## Key Changes

- **New `--agent` / `-a` flag and `--no-agent` flag**
  - Supports `claude`, `codex`, and `cursor` as agent values
- Interactive prompt shown when no flag is provided, with a "None"
option to skip
- `--no-agent` skips the prompt entirely, matching the `--no-deps` /
`--no-git` pattern

- **Runtime skill download via GitHub tarball**
- New `download-skill.ts` module reuses the same `codeload.github.com`
tarball + filter approach as `download-template.ts`
- Downloads `tools/claude-plugin/skills/payload/` and extracts it to the
agent's skill directory
- Claude uses `.claude/skills/payload/`, Codex and Cursor use
`.agents/skills/payload/`
  - Non-fatal on failure — project creation continues with a warning

- **Agent config file at project root**
  - Claude → `CLAUDE.md`, Codex/Cursor → `AGENTS.md` (never both)
  - Points the agent to the installed skill location for discoverability
  - Only written on successful skill download

- **Removed static agent files from templates**
  - Deleted `templates/_agents/` directory (source for copied rules)
- Deleted `AGENTS.md` and `.cursor/rules/` from all 8 templates (~43k
lines removed)
- Stripped `skipAgents` / `copyAgentsFiles` logic from
`generate-template-variations.ts`

- **Added Common Gotchas and Best Practices to SKILL.md**
- Closes a content gap vs. the old `AGENTS.md` — same 10 gotchas and 5
best-practice categories now in the skill

## Design Decisions

Agent selection follows the existing `select-db.ts` pattern: check CLI
flag first, validate, fall back to interactive prompt. This keeps the
codebase consistent and the new feature immediately familiar to anyone
who has worked on CPA.

The skill is downloaded at runtime rather than bundled into the CPA
package. This means the skill content always matches the latest `main`
branch without requiring a CPA release. The `--branch` flag (already
used for template downloads) controls which branch the skill is fetched
from, keeping template and skill versions in sync.

Codex and Cursor both use `.agents/skills/` (the universal skills
directory convention), while Claude uses its own `.claude/skills/`. The
mapping is defined in a single `agentChoices` array in
`select-agent.ts`.

The old `AGENTS.md` was a single 1,141-line file loaded automatically by
agents. The new skill is 393 lines in `SKILL.md` plus 6,243 lines across
11 reference docs (6,636 total). To preserve the quick-hit value of the
old file, Common Gotchas and Best Practices sections were added to
`SKILL.md`. A root-level `CLAUDE.md` or `AGENTS.md` points agents to the
skill for discoverability.

## Overall Flow

```mermaid
sequenceDiagram
    participant User
    participant CPA as create-payload-app
    participant GitHub

    User->>CPA: npx create-payload-app --agent claude
    CPA->>CPA: Parse template, select DB
    CPA->>CPA: selectAgent() — validates flag or shows prompt
    CPA->>CPA: Download template, configure config, manage env
    CPA->>GitHub: GET codeload.github.com/.../tar.gz/main
    GitHub-->>CPA: Tarball (filtered to skills/payload/)
    CPA->>CPA: Extract to .claude/skills/payload/
    CPA->>CPA: Write CLAUDE.md at project root
    CPA->>CPA: Install deps, init git
    CPA-->>User: Project ready with Payload skill installed
```

Author: denolfe

packages/create-payload-app/src/lib/create-project.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'
 import path from 'path'
 
 import type {
+  AgentType,
   CliArgs,
   DbDetails,
   PackageManager,
@@ -18,9 +19,11 @@ import { debug, error, info, warning } from '../utils/log.js'
 import { configurePayloadConfig } from './configure-payload-config.js'
 import { configurePluginProject } from './configure-plugin-project.js'
 import { downloadExample } from './download-example.js'
+import { downloadSkill } from './download-skill.js'
 import { downloadTemplate } from './download-template.js'
 import { generateSecret } from './generate-secret.js'
 import { manageEnvFiles } from './manage-env-files.js'
+import { getAgentChoice } from './select-agent.js'
 
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
@@ -72,14 +75,15 @@ type TemplateOrExample =
 
 export async function createProject(
   args: {
+    agentType?: AgentType
     cliArgs: CliArgs
     dbDetails?: DbDetails
     packageManager: PackageManager
     projectDir: string
     projectName: string
   } & TemplateOrExample,
 ): Promise<void> {
-  const { cliArgs, dbDetails, packageManager, projectDir, projectName } = args
+  const { agentType, cliArgs, dbDetails, packageManager, projectDir, projectName } = args
 
   if (cliArgs['--dry-run']) {
     debug(`Dry run: Creating project in ${chalk.green(projectDir)}`)
@@ -170,6 +174,31 @@ export async function createProject(
     template: 'template' in args ? args.template : undefined,
   })
 
+  if (agentType) {
+    spinner.message('Installing agent skill...')
+    try {
+      await downloadSkill({
+        agentType,
+        branch: cliArgs['--branch'] || undefined,
+        debug: cliArgs['--debug'],
+        projectDir,
+      })
+
+      const { configFile, skillsDir } = getAgentChoice(agentType)
+      const skillPath = `${skillsDir}/payload`
+      const configContent =
+        configFile === 'CLAUDE.md'
+          ? `# Claude Code\n\nThis project uses the Payload CMS skill at \`${skillPath}/\`.\nStart with \`${skillPath}/SKILL.md\` for a quick reference, then see \`${skillPath}/reference/\` for detailed docs.\n`
+          : `# Agents\n\nThis project uses the Payload CMS skill at \`${skillPath}/\`.\nStart with \`${skillPath}/SKILL.md\` for a quick reference, then see \`${skillPath}/reference/\` for detailed docs.\n`
+      await fse.writeFile(path.resolve(projectDir, configFile), configContent)
+    } catch (err) {
+      if (cliArgs['--debug'] && err instanceof Error) {
+        debug(`Failed to download skill: ${err.message}`)
+      }
+      warning('Could not download agent skill. You can install it manually later.')
+    }
+  }
+
   if (!cliArgs['--no-deps']) {
     info(`Using ${packageManager}.\n`)
     spinner.message('Installing dependencies...')

packages/create-payload-app/src/lib/download-skill.ts

@@ -0,0 +1,53 @@
+import fse from 'fs-extra'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import path from 'path'
+import { x } from 'tar'
+
+import type { AgentType } from '../types.js'
+
+import { debug as debugLog } from '../utils/log.js'
+import { getSkillsDir } from './select-agent.js'
+
+export async function downloadSkill(args: {
+  agentType: AgentType
+  branch?: string
+  debug?: boolean
+  projectDir: string
+}): Promise<void> {
+  const { agentType, branch = 'main', debug, projectDir } = args
+
+  const skillsDir = getSkillsDir(agentType)
+  const destDir = path.join(projectDir, skillsDir, 'payload')
+
+  await fse.mkdirp(destDir)
+
+  const url = `https://codeload.github.com/payloadcms/payload/tar.gz/${branch}`
+  const filter = `payload-${branch.replace(/^v/, '').replaceAll('/', '-')}/tools/claude-plugin/skills/payload/`
+
+  if (debug) {
+    debugLog(`Downloading skill for agent: ${agentType}`)
+    debugLog(`Skill codeload url: ${url}`)
+    debugLog(`Skill filter: ${filter}`)
+    debugLog(`Skill destination: ${destDir}`)
+  }
+
+  const res = await fetch(url)
+
+  if (!res.ok) {
+    throw new Error(`Failed to download skill: ${res.status} ${res.statusText} from ${url}`)
+  }
+
+  if (!res.body) {
+    throw new Error(`Failed to download skill: empty response from ${url}`)
+  }
+
+  await pipeline(
+    Readable.from(res.body as unknown as NodeJS.ReadableStream),
+    x({
+      cwd: destDir,
+      filter: (p) => p.includes(filter),
+      strip: filter.split('/').length - 1,
+    }),
+  )
+}

packages/create-payload-app/src/lib/select-agent.ts

@@ -0,0 +1,73 @@
+import * as p from '@clack/prompts'
+
+import type { AgentType, CliArgs } from '../types.js'
+
+type AgentChoice = {
+  /** File to write at project root pointing agents to the skill */
+  configFile: 'AGENTS.md' | 'CLAUDE.md'
+  label: string
+  skillsDir: string
+  value: AgentType
+}
+
+export const agentChoices: AgentChoice[] = [
+  { configFile: 'CLAUDE.md', label: 'Claude Code', skillsDir: '.claude/skills', value: 'claude' },
+  { configFile: 'AGENTS.md', label: 'Codex', skillsDir: '.agents/skills', value: 'codex' },
+  { configFile: 'AGENTS.md', label: 'Cursor', skillsDir: '.agents/skills', value: 'cursor' },
+]
+
+const validAgentValues = agentChoices.map((c) => c.value)
+
+export function getAgentChoice(agentType: AgentType): AgentChoice {
+  const choice = agentChoices.find((c) => c.value === agentType)
+  if (!choice) {
+    throw new Error(`Unknown agent type: ${agentType}`)
+  }
+  return choice
+}
+
+export function getSkillsDir(agentType: AgentType): string {
+  return getAgentChoice(agentType).skillsDir
+}
+
+export async function selectAgent(args: { cliArgs: CliArgs }): Promise<AgentType | undefined> {
+  const { cliArgs } = args
+
+  if (cliArgs['--no-agent']) {
+    return undefined
+  }
+
+  if (cliArgs['--agent']) {
+    const value = cliArgs['--agent'] as AgentType
+    if (!validAgentValues.includes(value)) {
+      throw new Error(
+        `Invalid agent type: ${cliArgs['--agent']}. Valid types are: ${validAgentValues.join(', ')}`,
+      )
+    }
+    return value
+  }
+
+  const selected = await p.select<
+    { label: string; value: 'none' | AgentType }[],
+    'none' | AgentType
+  >({
+    message: 'Select a coding agent to install the Payload skill for',
+    options: [
+      ...agentChoices.map((choice) => ({
+        label: choice.label,
+        value: choice.value,
+      })),
+      { label: 'None', value: 'none' as const },
+    ],
+  })
+
+  if (p.isCancel(selected)) {
+    process.exit(0)
+  }
+
+  if (selected === 'none') {
+    return undefined
+  }
+
+  return selected
+}

packages/create-payload-app/src/main.ts

@@ -16,6 +16,7 @@ import { getNextAppDetails, initNext } from './lib/init-next.js'
 import { manageEnvFiles } from './lib/manage-env-files.js'
 import { parseProjectName } from './lib/parse-project-name.js'
 import { parseTemplate } from './lib/parse-template.js'
+import { selectAgent } from './lib/select-agent.js'
 import { selectDb } from './lib/select-db.js'
 import { getValidTemplates, validateTemplate } from './lib/templates.js'
 import { updatePayloadInProject } from './lib/update-payload-in-project.js'
@@ -36,6 +37,7 @@ export class Main {
     // @ts-expect-error bad typings
     this.args = arg(
       {
+        '--agent': String,
         '--branch': String,
         '--db': String,
         '--db-accept-recommended': Boolean,
@@ -51,6 +53,9 @@ export class Main {
         // Next.js
         '--init-next': Boolean, // TODO: Is this needed if we detect if inside Next.js project?
 
+        // Agent
+        '--no-agent': Boolean,
+
         // Package manager
         '--no-deps': Boolean,
         '--use-bun': Boolean,
@@ -67,6 +72,7 @@ export class Main {
         '--dry-run': Boolean,
 
         // Aliases
+        '-a': '--agent',
         '-d': '--db',
         '-e': '--example',
         '-h': '--help',
@@ -231,7 +237,10 @@ export class Main {
           process.exit(1)
         }
 
+        const agentType = await selectAgent({ cliArgs: this.args })
+
         await createProject({
+          agentType,
           cliArgs: this.args,
           example,
           packageManager,
@@ -255,7 +264,9 @@ export class Main {
 
         switch (template.type) {
           case 'plugin': {
+            const agentType = await selectAgent({ cliArgs: this.args })
             await createProject({
+              agentType,
               cliArgs: this.args,
               packageManager,
               projectDir,
@@ -266,8 +277,10 @@ export class Main {
           }
           case 'starter': {
             const dbDetails = await selectDb(this.args, projectName, template)
+            const agentType = await selectAgent({ cliArgs: this.args })
 
             await createProject({
+              agentType,
               cliArgs: this.args,
               dbDetails,
               packageManager,

packages/create-payload-app/src/types.ts

@@ -3,6 +3,7 @@ import type arg from 'arg'
 import type { ALL_DATABASE_ADAPTERS, ALL_STORAGE_ADAPTERS } from './lib/ast/types.js'
 
 export interface Args extends arg.Spec {
+  '--agent': StringConstructor
   '--beta': BooleanConstructor
   '--branch': StringConstructor
   '--db': StringConstructor
@@ -17,6 +18,7 @@ export interface Args extends arg.Spec {
   '--local-example': StringConstructor
   '--local-template': StringConstructor
   '--name': StringConstructor
+  '--no-agent': BooleanConstructor
   '--no-deps': BooleanConstructor
   '--no-git': BooleanConstructor
   '--secret': StringConstructor
@@ -28,6 +30,7 @@ export interface Args extends arg.Spec {
 
   // Aliases
 
+  '-a': string
   '-e': string
   '-h': string
   '-n': string
@@ -93,3 +96,5 @@ export type NextAppDetails = {
 export type NextConfigType = 'cjs' | 'esm' | 'ts'
 
 export type StorageAdapterType = (typeof ALL_STORAGE_ADAPTERS)[number]
+
+export type AgentType = 'claude' | 'codex' | 'cursor'

packages/create-payload-app/src/utils/messages.ts

@@ -38,6 +38,11 @@ export function helpMessage(): void {
 
         {dim Available templates: ${formatTemplates(validTemplates)}}
 
+      -a     {underline agent_name}             Set coding agent (claude, codex, cursor)
+
+        {dim Installs the Payload skill for the selected agent}
+
+      --no-agent                    Skip agent skill installation
       --use-npm                     Use npm to install dependencies
       --use-yarn                    Use yarn to install dependencies
       --use-pnpm                    Use pnpm to install dependencies