create-agentic-app

创建 Agentic 应用

引导用户从“我想构建一些东西”开始，最终完成一个经过验证、正在 http://localhost:3000 运行的 Agentic Coding Starter Kit 项目。每一步都有明确的目的——在过程中向用户简要说明，让他们了解你代为做出的选择。

以下所有 Shell 命令均采用 POSIX 格式。在 Windows 上，请通过 Bash 工具（Git Bash / WSL）运行；所有受支持的平台都提供此工具。除非命令确实失败，否则不要将命令转换为 PowerShell。

此技能按线性流程进行，有两个真正的分支点：文件夹策略（步骤 2）和数据库选择（步骤 6）。其他内容均为是/否问题或默认选项。请按顺序完成各步骤——提前跳过会导致后续假设失效（例如，运行迁移需要配置 POSTGRES_URL）。

<pm> 替换说明： 在本文档及其参考资料中，<pm> 是所选包管理器的占位符——请按如下方式替换：

• pnpm → pnpm db:migrate、pnpm build:ci、pnpm dev
• npm → npm run db:migrate、npm run build:ci、npm run dev（调用 npm 脚本时必须使用 run）
• yarn → yarn db:migrate、yarn build:ci、yarn dev

1. 预检

在让用户选择之前，先检测他们已经安装了哪些工具。先进行探测，后续提问时才能只提供实际可用的选项——没有什么比先问“选 pnpm 还是 npm？”，然后才发现 pnpm 并未安装更糟糕了。

通过一次 Bash 调用批量并行运行以下六项探测：

node --version
pnpm --version
npm --version
yarn --version
docker --version
git --version

解读结果：

• Node.js 必须为 >= 18。如果 node --version 执行失败或返回的版本低于 18，请停止并告知用户从 https://nodejs.org 安装 Node 18+。不要继续——从此处开始的每个步骤都需要 Node。
• Git 必须已安装（脚手架工具会用到它）。如果缺少 Git，请停止并引导用户前往 https://git-scm.com/downloads。
• 包管理器：记下 pnpm、npm、yarn 中哪些检测成功。舍弃检测失败的选项——在步骤 3 中绝不将其作为选项提供。
• Docker 在此处为可选项；仅当用户在步骤 6 中选择本地数据库方案时才会用到。记下 docker --version 是否执行成功。

用一句简短的话向用户报告结果，例如：“检测到 Node 20.11、pnpm 9.1、npm 10.5、Docker 27.0、Git 2.43。未检测到 Yarn。”不要粘贴原始命令输出。

2. 文件夹策略

脚手架工具（create-agentic-app）拒绝写入非空目标目录。Agent 必须根据当前工作目录中的内容选择正确的调用方式。

在当前工作目录中运行 ls -A（包括点文件），查看目录内容。

2a. 空目录或仅含 Git 内容的工作目录

如果目录为空或只包含 .git，请直接在此目录中搭建项目。跳至步骤 3——稍后将在此运行 npx create-agentic-app@latest .。

2b. cwd 非空

通过 AskUserQuestion 询问用户：

“此文件夹不为空。你想把初始脚手架放在哪里？”

• 子文件夹 — 选择一个名称（默认：my-app）；初始脚手架将位于 ./<name>/。
• 此文件夹 — 我会先在临时目录中搭建脚手架，再把文件移回当前文件夹。如果你想让初始脚手架替换当前文件夹内容（或与其合并），请选此项。
• 取消 — 停止操作，让我先整理目录。

如果用户选择子文件夹：询问文件夹名称，默认为 my-app。第 4 步中的脚手架目标路径改为 ./<name>。跳过临时目录流程。

如果用户选择此文件夹：Agent 需要谨慎执行以下操作，因为隐藏文件和名称冲突都可能造成问题：

1. 选择一个尚不存在的临时目录名称：../$(basename "$PWD")-scaffold-tmp。如果该路径已被占用，则追加一个较短的随机后缀。
2. 在临时目录中运行脚手架工具（第 4 步中的 <target> = 临时目录）。临时目录方案始终传入 --skip-git——否则 CLI 会在临时目录中创建初始提交，而移回文件时 .git/ 目录会覆盖用户现有的 .git/，破坏其历史记录。
3. 脚手架搭建完成，并且其余可在临时目录中完成的步骤也已完成（环境文件、迁移等——这些操作都可以在临时目录中进行）后，将所有内容移回。使用包含隐藏文件的命令。POSIX：

   shopt -s dotglob
   mv ../<temp-dir>/* ./
   shopt -u dotglob
   

   这样可以一并移回 .env、.gitignore、.agents/、.claude/ 以及初始脚手架中的其他点文件。
4. 每次覆盖之前：如果临时目录中的文件与当前工作目录中的现有文件冲突（例如用户已有 README.md、.gitignore 或 .git/ 目录），请停止并通过 AskUserQuestion 询问用户要保留哪一个。不得悄悄覆盖用户的工作。
5. 移动完成后，删除现已空置的临时目录：rmdir ../<temp-dir>。

在执行此方案之前，先向用户说明，以便他们了解当前工作目录即将发生的变更。

3. 包管理器选择

通过 AskUserQuestion 询问，但仅显示第 1 步探测成功的选项：

“初始脚手架应使用哪个包管理器？”

• pnpm（仅在检测到时显示）— 初始脚手架推荐使用。
• npm（仅在检测到时显示）
• yarn（仅在检测到时显示）
• 由你替我选 — 由 Agent 决定。

如果用户选择“由你替我选”，则根据已安装情况，优先顺序为：pnpm → npm → yarn。如果第 1 步中 pnpm --version 执行失败，切勿推荐 pnpm——仅为满足偏好而安装它会让用户感到困扰。

记住选择的 <pm>，供后续每一步使用。

4. 运行脚手架

npx create-agentic-app@latest <target> --package-manager <pm> --yes

对于 临时目录变体（步骤 2b“此文件夹”），在上述命令中添加 --skip-git——原因请参阅步骤 2b。

其中，<target> 是步骤 2 中的路径（., ./my-app 或 ../<temp-dir>），<pm> 是 pnpm、npm 或 yarn（仅名称，不带 --use- 前缀）。--yes 标志会自动确认 CLI 的“目录非空”提示；如果不加此标志，CLI 会以交互方式询问，并在 Bash 工具下挂起。请注意，只有当 <target> 是一个有名称且非空的目录时，CLI 才会要求确认；当 <target> 为 . 时，无论当前文件夹中的内容如何，CLI 都会直接写入，这就是步骤 2 的文件夹策略很重要的原因。

将脚手架工具的输出流式传给用户，让他们了解正在发生什么。如果 CLI 报错（注册表超时、权限问题等），请原样显示确切的错误消息并停止。不要尝试猜测并自行恢复——大多数脚手架工具故障都需要用户处理（网络、npm 配置、权限）。

CLI 还会自动运行 <pm> install 和 git init（除非使用了 --skip-git）。关键是：CLI 使用 stdio: 'pipe' 捕获安装输出，因此安装失败时只会打印警告，CLI 仍会以 0 退出。 继续之前，请确认依赖确实已安装：

test -d <target>/node_modules && ls <target>/node_modules | head -n 5

如果 node_modules/ 不存在或几乎为空，请在 <target> 内运行 <pm> install 后再继续。否则之后运行 db:migrate 时会出现令人困惑的 Cannot find module 'drizzle-kit' 错误，白白浪费用户的时间。

脚手架创建完成后，接下来的流程都应在生成的目录内执行 cd。后续命令都假设你已进入该目录。对于临时目录变体，暂时运行 cd ../<temp-dir>——步骤 7（迁移后）之后，你会将文件移回原始文件夹，再 cd 回去。在临时目录内运行迁移没有问题；.env 就在那里。

5. 配置 .env

Starter 附带了包含合理默认值但缺少密钥的 env.example。请设置 .env：

1. 如果 .env 不存在，则复制模板：

   cp env.example .env
   

2. 生成强度足够的 BETTER_AUTH_SECRET（env.example 中提供的值只是占位符——在任何非临时本地开发环境中，都必须替换该值）：

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

   将输出写入 .env，作为 BETTER_AUTH_SECRET=<value>。
3. 确认已设置 NEXT_PUBLIC_APP_URL=http://localhost:3000（模板中已设置）。
4. 暂时将以下变量留空——后续步骤会根据用户选择填入：
   • OPENROUTER_API_KEY（步骤 8）
   • BLOB_READ_WRITE_TOKEN（步骤 9b）
   • POLAR_WEBHOOK_SECRET / POLAR_ACCESS_TOKEN（步骤 9b）

告诉用户：“我已设置 .env 并生成新的身份验证密钥。接下来配置数据库 URL 和可选集成。”

6. 数据库设置

通过 AskUserQuestion 询问：

“你想使用哪种 PostgreSQL 设置？”

• 本地 Docker （仅当步骤 1 中 docker --version 执行成功时显示）——推荐用于本地开发；使用项目附带的 docker-compose.yml。
• Neon——云端免费无服务器 Postgres（适合个人开发者和小型项目）。
• Vercel Postgres——如果你本来就计划部署到 Vercel，这是最佳选择。
• 自备数据库——你已经有 POSTGRES_URL。

用户选择后，现在读取 references/database.md，并按照对应分支的说明操作。该文件包含确切的命令、预期的连接字符串格式，以及每种路径的验证步骤。不要在此处粘贴这些细节——它们容易过时，也会让此工作流变得冗长。

所选分支完成后，.env 中就会有有效的 POSTGRES_URL。接下来进行迁移。

7. 运行迁移

<pm> db:migrate

这会应用 starter 预生成的迁移，并创建 Better Auth 表。样板项目已附带生成好的迁移，因此这里不需要运行 <pm> db:generate——只有之后用户更改架构时才需要运行该命令。

如果迁移失败，绝不要把 <pm> db:push 当作快捷方式运行。根据项目的 AGENTS.md 规则：drizzle push 会绕过迁移历史并造成难以恢复的偏差。如果 db:migrate 失败，请向用户提供确切的错误信息——原因几乎总是 POSTGRES_URL 错误、数据库无法访问或身份验证凭据过期——并表示在他们修复根本原因后可以重试一次。

8. AI 功能——选择启用

询问用户：

“要启用 AI 功能吗？starter 通过 OpenRouter 接入了 Vercel AI SDK，因此无需更改代码即可切换模型。你也可以跳过这一步，以后再添加。”

如果回答是：

1. 引导用户前往 https://openrouter.ai/settings/keys 创建 API 密钥。
2. 请用户粘贴密钥；在 .env 中设置 OPENROUTER_API_KEY=<key>。
3. 确认默认的 OPENROUTER_MODEL="openai/gpt-5-mini" 是否合适，或者让用户换成 https://openrouter.ai/models 上列出的任意模型。

如果回答否：将 OPENROUTER_API_KEY 留空。如果调用聊天路由 /api/chat，它会返回错误，但应用的其余部分仍可正常运行。请告知用户这一点，以免他们之后感到意外。

9. 身份验证——告知，不要配置

大致使用以下措辞告知用户：

starter 默认启用了电子邮件 + 密码身份验证——对于 MVP 来说已经足够。如果你想添加社交登录（Google、GitHub 等），我可以通过 Better Auth 帮你接入；但我建议先从电子邮件/密码开始，等确实需要时再添加 OAuth。

如果用户现在想要 OAuth，请阅读 references/auth.md。该文件链接到 Better Auth 提供商文档，会让 Agent 使用 WebFetch 获取相关页面，并提醒你保留电子邮件/密码登录，同时启用任何新增的提供商。否则，请跳过——以后再添加 OAuth 成本很低，而且可以减少初期的操作负担。

9b. 生产环境扩展——选择启用（单次多选）

通过 AskUserQuestion 一次性询问（多选）：

“你希望现在配置哪些生产环境集成？可选择任意适用项，也可以全部留空以跳过并保持配置精简——以后还可以再添加。”

• 使用 Vercel Blob 上传文件
• 使用 Polar 处理支付
• 事务性电子邮件（Resend / Postmark / 等）

如果用户没有选择任何项目，则完全跳过此步骤——不要加载参考文件。加载用户不需要的文档会浪费他们的上下文预算。

对于用户确实选择的每个项目，请阅读 references/production-extras.md 中对应的章节，并引导他们完成配置。该文件分别介绍了 Blob、Polar+ngrok 和电子邮件——只需查看适用的章节。

10. 验证构建

<pm> build:ci

请使用 build:ci（而非 <pm> build），因为默认的 build 脚本也会运行迁移——而我们已在第 7 步完成迁移。重复运行迁移虽然无害，但会更慢，也会产生更多输出。

如果构建失败，请向用户提供确切的错误信息。常见原因包括缺少环境变量（重新检查 .env）或 Node 模块过期（必要时再次运行 <pm> install）。不要通过“边修边推进”来掩盖构建失败——此阶段的大多数构建错误都意味着配置有误，之后会给开发服务器带来持续问题。

11. 启动开发服务器并验证

在后台启动开发服务器：

<pm> dev

通过 Bash 工具的 run_in_background: true 选项运行，这样其余验证就能同时进行。Bash 工具会立即返回——Next.js 需要几秒钟来编译并绑定到端口 3000，因此不要马上运行 curl，否则会遇到连接被拒绝的错误，并误以为应用出了问题。

通过以下任一方式等待服务器就绪：

• 首选：使用 Monitor 工具监控后台进程，并等待包含 Ready in 或 Local: http://localhost:3000 的日志行。这是 Next 发出的端口已绑定信号。
• 备选：每次间隔 2 秒重试 HTTP 检查，共 5 次。将连接被拒绝视为“尚未就绪，重试”；将任何 HTTP 响应（即使是 500）视为“服务器已启动，现在检查响应正文”。

然后验证以下三项：

1. 进程仍在运行。 启动时崩溃的开发服务器不会响应——在下结论前检查后台进程输出。
2. http://localhost:3000 返回 HTTP 200。 使用 Bash 工具：

   curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000
   

   在没有 curl 的 Windows 上，改用 PowerShell 工具运行：(Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing).StatusCode。
3. 开发服务器的标准输出／标准错误中没有致命错误——扫描后台输出，查找堆栈跟踪、数据库连接被拒绝或缺少环境变量的警告。

如果其中任何一项失败，常见原因如下：

• 端口 3000 已被占用——另一个进程正在使用该端口。告知用户，并关闭另一个进程或运行 PORT=3001 <pm> dev。
• 数据库连接被拒绝——Docker 容器已停止、POSTGRES_URL 错误，或托管数据库已暂停。重新检查第 6 步。
• 缺少或强度不足的 BETTER_AUTH_SECRET——重新检查第 5 步并重新生成。

在宣告成功前修复故障——半运行状态的应用比坦诚地报告错误更糟。

12. 报告成功

按以下顺序告知用户：

1. 应用已在 http://localhost:3000 运行。
2. .env 的位置（绝对路径），并用一句话概述哪些集成已配置、哪些为空——例如：“auth secret 已设置，Postgres 已设置（Docker），OpenRouter 已设置，Blob/Polar/email 为空”。
3. 一条入门提示词，供用户粘贴到 Agent 中以开始构建实际应用。使用此模板（与 README 一致）：

I am using the Agentic Coding Starter Kit. Treat the existing app as boilerplate that should be replaced by the product I describe.

Use the project instructions in AGENTS.md or CLAUDE.md. During planning, ask clarifying questions before making assumptions. During implementation, split the work into small chunks, use sub-agents where useful, follow DESIGN.md for UI, preserve the existing tech stack unless there is a good reason to change it, and run lint, typecheck, and build before finishing.

What I want to build:
[Describe your app here]

4. 指出此项目中将影响后续 Agent 行为的三个文件：AGENTS.md、CLAUDE.md 和 DESIGN.md。

最终消息保持简短——用户想开始构建，而不是阅读一大段文字。

发布说明

如果用户询问其他人如何安装此技能，回答如下：

npx skills add <owner>/<repo>@create-agentic-app --agent claude-code

必须使用 --agent claude-code 标志——否则，安装程序会将技能放入项目根目录下 37+ 个 IDE 适配器文件夹中，而这通常不是任何人想要的结果。