create-agentic-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Agentic App

Walk the user from "I want to build something" to a verified, running Agentic Coding Starter Kit project at

http://localhost:3000

. Every step has a clear purpose — explain it briefly to the user as you go, so they understand the choices being made on their behalf.

All shell commands below are written in POSIX form. On Windows, run them through the Bash tool (Git Bash / WSL), which is available on every supported platform. Do not translate to PowerShell unless a command actually fails.

This skill is linear with two real branch points: folder strategy (Step 2) and database choice (Step 6). Everything else is a yes/no or a default. Move through the steps in order — skipping ahead breaks assumptions downstream (e.g. migrations require a configured

POSTGRES_URL

<pm>
substitution: Throughout this file and the references,

<pm>

is a placeholder for the chosen package manager — substitute as follows:

pnpm

→

pnpm db:migrate

pnpm build:ci

pnpm dev

npm

→

npm run db:migrate

npm run build:ci

npm run dev

(the

run

is required for npm script invocation)

yarn

→

yarn db:migrate

yarn build:ci

yarn dev

引导用户从「我想开发一个应用」到拥有一个已验证可运行的Agentic Coding Starter Kit项目，运行在

http://localhost:3000

。每一步都有明确的目的——执行时向用户简要说明，让他们了解为其做出的选择。

以下所有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. Pre-flight Checks

1. 预检检查

Detect what the user already has installed before asking them to pick anything. Probing first means later questions only offer real options — nothing is worse than asking "pnpm or npm?" and then discovering pnpm isn't installed.

Run all six probes in parallel via a single batch of Bash calls:

bash

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

Interpret the results:

Node.js must be
```
>= 18
```
. If
```
node --version
```
fails or returns < 18, stop and tell the user to install Node 18+ from https://nodejs.org. Do not continue — every step from here on requires Node.
Git must be present (the scaffolder uses it). If missing, stop and direct the user to https://git-scm.com/downloads.
Package managers: remember which of
```
pnpm
```
,
```
npm
```
,
```
yarn
```
succeeded. Discard the ones that failed — you will never offer them as options in Step 3.
Docker is optional here; it only matters if the user picks the local-DB path in Step 6. Note whether
```
docker --version
```
succeeded.

Report findings as one short sentence to the user — for example: "Found Node 20.11, pnpm 9.1, npm 10.5, Docker 27.0, Git 2.43. Yarn not detected." Do not dump raw command output.

在让用户选择任何选项之前，先检测用户已安装的工具。提前探测意味着后续问题只会提供真实可用的选项——最糟糕的情况莫过于询问「pnpm还是npm？」之后，发现用户并未安装pnpm。

通过一组Bash调用并行运行以下6项探测：

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.js。
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. Folder Strategy

2. 文件夹策略

The scaffolder (

create-agentic-app

) refuses to write into a non-empty target. The agent has to pick the right invocation based on what is in the current working directory.

Run

ls -A

(includes dotfiles) in the cwd to see what is there.

脚手架工具

create-agentic-app

拒绝写入非空目标目录。因此需要根据当前工作目录的内容选择正确的调用方式。

在当前工作目录执行

ls -A

（包含隐藏文件）查看目录内容。

2a. Empty or git-only cwd

2a. 当前目录为空或仅包含.git文件夹

If the directory is empty or only contains

.git

, scaffold directly in place. Skip to Step 3 — you will run

npx create-agentic-app@latest .

later.

如果目录为空或仅包含

.git

文件夹，则直接在当前目录搭建项目。跳至步骤3——后续将执行

npx create-agentic-app@latest .

。

2b. Non-empty cwd

2b. 当前目录非空

Ask the user via

AskUserQuestion

"This folder isn't empty. Where do you want the starter scaffolded?"
Subfolder — pick a name (default:
my-app
); the starter lives at
./<name>/
.
This folder — I will scaffold into a temp directory and move the files back into the current folder. Use this if you want the starter to replace the current folder's contents (or merge with them).

Cancel — stop and let me sort the directory out first.

If they pick subfolder: ask for the folder name, default to

my-app

. The scaffold target in Step 4 becomes

./<name>

. Skip the temp-dir dance.

If they pick this folder: the agent does the following carefully, because hidden files and name collisions both bite:

Pick a temp dir name that does not already exist:
```
../$(basename "$PWD")-scaffold-tmp
```
. If that path is already taken, append a short random suffix.
Run the scaffolder in the temp dir (Step 4 with
```
<target>
```
= the temp dir). Always pass
--skip-git
for the temp-dir variant — otherwise the CLI creates an initial commit inside the temp dir, and the
```
.git/
```
directory will overwrite the user's existing
```
.git/
```
when you move files back, destroying their history.
After scaffolding completes and the rest of the steps that can be done inside the temp dir are done (env file, migrations, etc. — they all work from inside the temp dir), move everything back. Use a command that includes hidden files. POSIX:
bash
```
shopt -s dotglob
mv ../<temp-dir>/* ./
shopt -u dotglob
```
This catches
```
.env
```
,
```
.gitignore
```
,
```
.agents/
```
,
```
.claude/
```
, and any other dotfiles the starter ships.
Before each overwrite: if a file in the temp dir collides with an existing file in the cwd (e.g. the user already has a
```
README.md
```
, a
```
.gitignore
```
, or a
```
.git/
```
directory), stop and ask the user via
```
AskUserQuestion
```
which one to keep. Do not silently clobber their work.
After the move, remove the now-empty temp dir:
```
rmdir ../<temp-dir>
```
.

Document this plan to the user before running it so they know what is about to happen to their cwd.

通过

AskUserQuestion

询问用户：

"当前文件夹非空。你希望在哪里搭建项目模板？"
子文件夹 —— 输入文件夹名称（默认：
my-app
）；项目将位于
./<name>/
。
当前文件夹 —— 我会先在临时目录搭建项目，然后将文件移回当前文件夹。如果你希望项目模板替换（或合并）当前文件夹的内容，请选择此选项。

取消 —— 停止操作，让我先整理当前目录。

如果用户选择子文件夹：询问文件夹名称，默认值为

my-app

。步骤4中的搭建目标路径为

./<name>

。跳过临时目录操作。

如果用户选择当前文件夹：请谨慎执行以下操作，因为隐藏文件和名称冲突可能会导致问题：

选择一个不存在的临时目录名称：
```
../$(basename "$PWD")-scaffold-tmp
```
。如果该路径已存在，请添加一个短随机后缀。
在临时目录中运行脚手架工具（步骤4中的
```
<target>
```
为临时目录路径）。临时目录模式必须添加
--skip-git
参数——否则CLI会在临时目录中创建初始提交，当你将文件移回时，
```
.git/
```
目录会覆盖用户现有的
```
.git/
```
目录，破坏其版本历史。
搭建完成并完成所有可在临时目录中执行的步骤（如环境文件配置、数据库迁移等——这些步骤在临时目录中均可正常执行）后，将所有文件移回原目录。使用包含隐藏文件的命令。POSIX命令如下：
bash
```
shopt -s dotglob
mv ../<temp-dir>/* ./
shopt -u dotglob
```
此命令会捕获
```
.env
```
、
```
.gitignore
```
、
```
.agents/
```
、
```
.claude/
```
等所有模板包含的隐藏文件。
覆盖前确认：如果临时目录中的文件与当前目录中的现有文件冲突（例如用户已有
```
README.md
```
、
```
.gitignore
```
或
```
.git/
```
目录），请停止操作并通过
```
AskUserQuestion
```
询问用户保留哪个文件。不要静默覆盖用户的文件。
文件移动完成后，删除空的临时目录：
```
rmdir ../<temp-dir>
```
。

在执行此计划前，请向用户说明操作内容，让他们了解当前目录即将发生的变化。

3. Package-Manager Choice

3. 包管理器选择

Ask via

AskUserQuestion

, but only show options that succeeded in Step 1's probe:

"Which package manager should the starter use?"

pnpm (only show if detected) — recommended by the starter.

npm (only show if detected)

yarn (only show if detected)

You pick for me — defer to the agent.

If the user picks "you pick", prefer in order:

pnpm

→

npm

→

yarn

based on what is installed. Never suggest pnpm if

pnpm --version

failed in Step 1 — installing it just to satisfy a preference frustrates users.

Remember the chosen

<pm>

for every subsequent step.

通过

AskUserQuestion

询问用户，但仅显示步骤1中探测成功的选项：

"项目模板应使用哪个包管理器？"

pnpm (仅在检测到后显示) —— 模板推荐使用。

npm (仅在检测到后显示)

yarn (仅在检测到后显示)

由你选择 —— 由代理决定。

如果用户选择"由你选择"，优先顺序为：

pnpm

→

npm

→

yarn

（基于已安装的工具）。如果步骤1中

pnpm --version

执行失败，永远不要推荐pnpm——为了满足偏好而让用户安装工具会引起用户不满。

记录所选的

<pm>

，后续所有步骤均会用到。

4. Run the Scaffold

4. 运行脚手架

bash

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

For the temp-dir variant (Step 2b "this folder"), add

--skip-git

to the command above — see Step 2b for why.

Where

<target>

is the path from Step 2 (

./my-app

, or

../<temp-dir>

) and

<pm>

pnpm

npm

, or

yarn

(the name only — no

--use-

prefix). The

--yes

flag auto-confirms the CLI's "directory is not empty" prompt; without it, the CLI prompts interactively and will hang under the Bash tool. Note that the CLI only prompts for confirmation when

<target>

is a named non-empty directory — when

<target>

, the CLI happily writes into the current folder regardless of contents, which is why Step 2's folder strategy matters.

Stream the scaffolder's output to the user so they can see what is happening. If the CLI errors (registry timeout, permissions, etc.), surface the exact error message and stop. Do not try to recover by guessing — most scaffolder failures need user-level fixes (network, npm config, permissions).

The CLI also runs

<pm> install

and

git init

(unless

--skip-git

) for you automatically. Critically: the CLI captures the install output with
stdio: 'pipe'
, so a failed install only prints a warning and the CLI still exits 0. Before continuing, verify dependencies actually installed:

bash

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

node_modules/

is missing or near-empty, run

<pm> install

from inside

<target>

before moving on. Otherwise

db:migrate

will fail later with a confusing

Cannot find module 'drizzle-kit'

error and you will have wasted the user's time.

After the scaffold completes,

cd

into the scaffolded directory for the rest of the flow. Subsequent commands assume you are inside it. For the temp-dir variant,

cd ../<temp-dir>

for now — you will move the files back into the original folder after Step 7 (post-migration) and then

cd

back. Running migrations from inside the temp dir is fine; the

.env

is right there.

bash

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状态码退出。在继续执行后续步骤前，请验证依赖是否已实际安装：

bash

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

如果

node_modules/

缺失或几乎为空，请在

<target>

目录中执行

<pm> install

后再继续。否则后续

db:migrate

会因找不到

drizzle-kit

模块而失败，浪费用户时间。

搭建完成后，进入搭建好的目录执行后续步骤。后续命令均假设你已处于该目录中。对于临时目录模式，请先进入

../<temp-dir>

——完成步骤7（数据库迁移）后，将文件移回原目录，再返回原目录。在临时目录中执行数据库迁移是可行的，因为

.env

文件就在该目录中。

5. Configure

.env

5. 配置

.env

The starter ships an

env.example

with sensible defaults but missing secrets. Set up

.env

Copy the template if
```
.env
```
does not already exist:
bash
```
cp env.example .env
```
Generate a strong
```
BETTER_AUTH_SECRET
```
(the value shipped in
```
env.example
```
is a placeholder — replacing it is non-negotiable for any environment beyond throwaway local dev):
bash
```
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
Take the output and write it into
```
.env
```
as
```
BETTER_AUTH_SECRET=<value>
```
.
Confirm
```
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
is set (it already is in the template).
Leave the following blank for now — later steps populate them based on user opt-in:
- ```
OPENROUTER_API_KEY
```
  (Step 8)
- ```
BLOB_READ_WRITE_TOKEN
```
  (Step 9b)
- ```
POLAR_WEBHOOK_SECRET
```
  /
```
POLAR_ACCESS_TOKEN
```
  (Step 9b)

Tell the user: "I have set up

.env

with a fresh auth secret. Database URL and optional integrations come next."

项目模板包含一个

env.example

文件，带有合理的默认值但缺少密钥。请按以下步骤配置

.env

：

如果
```
.env
```
文件不存在，复制模板文件：
bash
```
cp env.example .env
```
生成一个强
```
BETTER_AUTH_SECRET
```
（
```
env.example
```
中提供的值是占位符——除了临时本地开发环境，必须替换此值）：
bash
```
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
将输出结果写入
```
.env
```
文件，格式为
```
BETTER_AUTH_SECRET=<value>
```
。
确认
```
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
已设置（模板中已默认设置）。
暂时保留以下字段为空——后续步骤会根据用户的选择填充：
- ```
OPENROUTER_API_KEY
```
  （步骤8）
- ```
BLOB_READ_WRITE_TOKEN
```
  （步骤9b）
- ```
POLAR_WEBHOOK_SECRET
```
  /
```
POLAR_ACCESS_TOKEN
```
  （步骤9b）

告知用户："我已为

.env

配置了新的认证密钥。数据库URL和可选集成将在后续步骤中配置。"

6. Database Setup

6. 数据库设置

Ask via

AskUserQuestion

"Which PostgreSQL setup do you want?"
Local Docker (only show if
docker --version
succeeded in Step 1) — recommended for local development; uses the included
docker-compose.yml
.
Neon — free serverless Postgres in the cloud (good for solo dev and small projects).

Vercel Postgres — best if you plan to deploy to Vercel anyway.
Bring your own — you have a
POSTGRES_URL
already.

Once the user picks, now read
references/database.md
and follow the section for the chosen branch. That file has the exact commands, the connection-string format to expect, and the validation steps for each path. Do not paste those details here — they go stale and crowd this workflow.

After the chosen branch completes, you will have a valid

POSTGRES_URL

.env

. Move on to migrations.

通过

AskUserQuestion

询问用户：

"你希望使用哪种PostgreSQL设置？"
本地Docker (仅在步骤1中
docker --version
执行成功后显示) —— 推荐用于本地开发；使用项目中包含的
docker-compose.yml
。
Neon —— 免费的云端无服务器Postgres（适合个人开发和小型项目）。

Vercel Postgres —— 如果计划部署到Vercel，此选项最佳。
自定义数据库 —— 你已有
POSTGRES_URL
。

用户选择后，请阅读
references/database.md
并遵循对应分支的说明。该文件包含每种方案的确切命令、预期的连接字符串格式以及验证步骤。不要在此处粘贴这些细节——它们可能会过时并使本流程变得冗长。

完成所选分支的配置后，

.env

文件中将包含有效的

POSTGRES_URL

。继续执行数据库迁移步骤。

7. Run Migrations

7. 执行数据库迁移

bash

<pm> db:migrate

This applies the starter's pre-generated migrations and creates the Better Auth tables. The boilerplate already ships generated migrations, so you do not need

<pm> db:generate

here — that command is only relevant later when the user changes the schema.

Never run
<pm> db:push
as a shortcut if migrations fail. Per the project's

AGENTS.md

rule: drizzle push bypasses the migration history and creates drift that is painful to recover from. If

db:migrate

fails, surface the exact error to the user — it is almost always a wrong

POSTGRES_URL

, an unreachable database, or stale auth credentials — and offer to retry once they fix the underlying cause.

bash

<pm> db:migrate

此命令会应用项目模板预先生成的迁移文件并创建Better Auth表。模板已包含生成好的迁移文件，因此无需执行

<pm> db:generate

——该命令仅在用户后续修改 schema 时才需要。

永远不要使用
<pm> db:push
作为迁移失败的捷径。根据项目的

AGENTS.md

规则：drizzle push会绕过迁移历史，导致难以恢复的 schema 漂移。如果

db:migrate

失败，请向用户显示确切的错误信息——几乎总是因为

POSTGRES_URL

错误、数据库无法访问或认证凭证过期——并在用户修复根本原因后提供重试选项。

8. AI Capabilities — Opt-in

8. AI功能——可选启用

Ask the user:

"Do you want AI features enabled? The starter wires up the Vercel AI SDK via OpenRouter, which lets you swap models without code changes. You can skip this and add it later."

If yes:

Walk the user to https://openrouter.ai/settings/keys to create an API key.
Ask them to paste it; set
```
OPENROUTER_API_KEY=<key>
```
in
```
.env
```
.
Confirm the default
```
OPENROUTER_MODEL="openai/gpt-5-mini"
```
is fine, or let them swap it for any model listed at https://openrouter.ai/models.

If no: leave

OPENROUTER_API_KEY

blank. The chat route at

/api/chat

will return an error if invoked, but the rest of the app runs fine. Note this to the user so they are not surprised later.

询问用户：

"你希望启用AI功能吗？项目模板通过OpenRouter集成了Vercel AI SDK，无需修改代码即可切换模型。你可以跳过此步骤，稍后再添加。"

如果用户选择是：

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

如果用户选择否：保留

OPENROUTER_API_KEY

为空。当调用

/api/chat

路由时会返回错误，但应用的其余部分可正常运行。请告知用户此情况，避免后续产生困惑。

9. Authentication — Inform, Don't Configure

9. 认证——告知即可，无需配置

Tell the user, in roughly these words:

The starter ships with email + password authentication enabled by default — that is enough for an MVP. If you want social sign-in (Google, GitHub, etc.), I can add it via Better Auth — but I recommend starting with email/password and adding OAuth later when you actually need it.

If the user wants OAuth now, read
references/auth.md
. That file links the Better Auth provider docs, tells the agent to fetch the relevant page with WebFetch, and reminds you to keep email/password enabled alongside any new providers. Otherwise, skip it — adding OAuth is cheap to do later and adds friction up front.

用大致如下的语言告知用户：

项目模板默认启用了邮箱+密码认证——这足以支撑MVP（最小可行产品）。如果你需要社交登录（Google、GitHub等），我可以通过Better Auth添加——但我建议先从邮箱/密码认证开始，当你真正需要时再添加OAuth。

如果用户现在需要OAuth，请阅读
references/auth.md
。该文件链接了Better Auth的提供商文档，告知代理通过WebFetch获取相关页面，并提醒你在添加新提供商时保留邮箱/密码认证。否则，请跳过此步骤——后续添加OAuth成本很低，而提前添加会增加初始设置的复杂度。

9b. Production Extras — Opt-in (Single Multi-Select)

9b. 生产环境附加功能——可选启用（多选）

Ask once via

AskUserQuestion

(multi-select):

"Which production integrations do you want set up now? Pick any that apply, or leave them all unchecked to skip and keep the setup lean — you can add them later."

File uploads with Vercel Blob

Payments with Polar

Transactional email (Resend / Postmark / etc.)

If the user picks nothing, skip this step entirely — do not load the reference file. Loading docs the user does not need wastes their context budget.

For each item the user does pick, read the corresponding section of
references/production-extras.md
and walk them through it. That file has independent sections for Blob, Polar+ngrok, and email — only consult the ones that apply.

通过

AskUserQuestion

询问一次（多选）：

"你希望现在配置哪些生产环境集成？可以选择任意适用的选项，或全部不选以保持设置简洁——你可以稍后再添加。"

使用Vercel Blob进行文件上传

使用Polar处理支付

事务邮件（Resend / Postmark等）

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

对于用户选择的每个选项，请阅读
references/production-extras.md
中的对应章节并引导用户完成配置。该文件包含Blob、Polar+ngrok和邮件的独立章节——仅查阅适用的章节即可。

10. Verify the Build

10. 验证构建

bash

<pm> build:ci

Use

build:ci

(not

<pm> build

) because the default

build

script also runs migrations — and we already migrated in Step 7. Running them twice is harmless but slower and noisier.

If the build fails: surface the exact error to the user. Common causes are missing env vars (re-check

.env

) or stale Node modules (

<pm> install

again if needed). Do not paper over a build failure by "fixing forward" — most build errors at this stage indicate a misconfiguration that will haunt the dev server later.

bash

<pm> build:ci

使用

build:ci

（而非

<pm> build

），因为默认的

build

脚本也会执行数据库迁移——而我们已在步骤7中完成了迁移。重复执行迁移无害，但会更慢且输出更杂乱。

如果构建失败：向用户显示确切的错误信息。常见原因包括缺少环境变量（重新检查

.env

）或Node模块过时（必要时重新执行

<pm> install

）。不要通过"向前修复"来掩盖构建失败——此时的大多数构建错误表明存在配置问题，后续会影响开发服务器的运行。

11. Start the Dev Server and Verify

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

Start the dev server in the background:

bash

<pm> dev

Run this via the Bash tool's

run_in_background: true

option so the rest of the verification can run alongside it. The Bash tool returns immediately — Next.js needs a few seconds to compile and bind to port 3000, so do not curl right away or you will get a connection-refused error and falsely conclude the app is broken.

Wait for readiness one of two ways:

Preferred: use the
```
Monitor
```
tool to tail the background process and wait for a line containing
```
Ready in
```
or
```
Local:        http://localhost:3000
```
. That is Next's own signal that the port is bound.
Fallback: retry the HTTP check 5 times with a 2-second pause between attempts. Treat connection-refused as "not ready yet, retry"; treat any HTTP response (even 500) as "the server is up, now check the body".

Then verify three things:

The process is still alive. A dev server that crashed during boot will not respond — check the background process output before concluding.

HTTP 200 from
http://localhost:3000
. Use the Bash tool:

bash

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

On Windows without curl, fall back to PowerShell via the PowerShell tool:

(Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing).StatusCode

No fatal errors in the dev server's stdout/stderr — scan the background output for stack traces, DB connection refusals, or missing-env-var warnings.

If any of these fail, common causes to call out:

Port 3000 already in use — another process is bound to it. Tell the user, and either kill the other process or run
```
PORT=3001 <pm> dev
```
.
Database connection refused — Docker container stopped, wrong
```
POSTGRES_URL
```
, or the hosted DB is paused. Re-check Step 6.
BETTER_AUTH_SECRET
missing or weak — re-check Step 5 and regenerate.

Fix the failure before claiming success — a half-running app is worse than an honest error.

在后台启动开发服务器：

bash

<pm> dev

通过Bash工具的

run_in_background: true

选项执行此命令，以便后续验证步骤可并行执行。Bash工具会立即返回——Next.js需要几秒钟时间编译并绑定到3000端口，因此不要立即执行curl命令，否则会收到连接拒绝错误并错误地认为应用已损坏。

通过以下两种方式之一等待服务器就绪：

首选方式：使用
```
Monitor
```
工具跟踪后台进程，等待包含
```
Ready in
```
或
```
Local:        http://localhost:3000
```
的行。这是Next.js自身发出的端口已绑定的信号。
备选方式：重试HTTP检查5次，每次间隔2秒。将连接拒绝视为"尚未就绪，重试"；将任何HTTP响应（即使是500）视为"服务器已启动，现在检查响应内容"。

然后验证以下三点：

进程仍在运行。启动过程中崩溃的开发服务器不会响应——在得出结论前，请检查后台进程的输出。

http://localhost:3000
返回HTTP 200。使用Bash工具执行：

bash

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

在没有curl的Windows系统上，通过PowerShell工具执行：

(Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing).StatusCode

。

开发服务器的标准输出/错误中没有致命错误——扫描后台输出，查找堆栈跟踪、数据库连接拒绝或缺少环境变量的警告。

如果任何验证失败，请指出常见原因：

3000端口已被占用——另一个进程已绑定到该端口。告知用户，要么终止该进程，要么执行
```
PORT=3001 <pm> dev
```
。
数据库连接被拒绝——Docker容器已停止、
```
POSTGRES_URL
```
错误或托管数据库已暂停。重新检查步骤6。
BETTER_AUTH_SECRET
缺失或强度不足——重新检查步骤5并重新生成。

在宣布成功前修复所有失败——一个半运行的应用比明确的错误更糟糕。

12. Report Success

12. 报告成功

Tell the user, in this order:

The app is live at http://localhost:3000.
Where
.env
is (absolute path) and a one-line summary of which integrations are set versus blank — for example: "auth secret set, Postgres set (Docker), OpenRouter set, Blob/Polar/email blank".
A starter prompt they can paste into the agent to begin building their actual app. Use this template (matches the README):

text

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]

A pointer to the three files that will drive future agent behavior in this project:
```
AGENTS.md
```
,
```
CLAUDE.md
```
, and
```
DESIGN.md
```
.

Keep this final message short — the user wants to start building, not read a wall of text.

按以下顺序告知用户：

应用已上线，地址为http://localhost:3000。
.env
文件的位置（绝对路径）以及已配置和未配置集成的简要总结——例如："已设置认证密钥、Postgres（Docker）、OpenRouter，未设置Blob/Polar/邮件"。
启动提示，用户可将其粘贴到代理中开始开发实际应用。使用以下模板（与README一致）：

text

我正在使用Agentic Coding Starter Kit。请将现有应用视为模板，用我描述的产品替换它。

请遵循AGENTS.md或CLAUDE.md中的项目说明。规划阶段，请先提出澄清问题再做出假设。实现阶段，请将工作拆分为小块，在有用时使用子代理，遵循DESIGN.md进行UI设计，保留现有技术栈除非有充分理由更改，完成前运行lint、类型检查和构建。

我想要开发的应用：
[在此描述你的应用]

指向三个文件，这些文件将指导项目后续的代理行为：
```
AGENTS.md
```
、
```
CLAUDE.md
```
和
```
DESIGN.md
```
。

请保持最终消息简洁——用户想要开始开发，而不是阅读长篇大论。

Publishing Note

发布说明

If the user asks how other people can install this skill, the answer is:

bash

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

The

--agent claude-code

flag is required — without it, the installer drops the skill into 37+ IDE adapter folders at the project root, which is rarely what anyone wants.

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

bash

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

必须添加

--agent claude-code

参数——否则安装程序会将技能放入项目根目录的37+个IDE适配器文件夹中，这通常不是用户想要的。

create-agentic-app

Original

Translation

Create Agentic App

Create Agentic App

1. Pre-flight Checks

1. 预检检查

2. Folder Strategy

2. 文件夹策略

2a. Empty or git-only cwd

2a. 当前目录为空或仅包含.git文件夹

2b. Non-empty cwd

2b. 当前目录非空

3. Package-Manager Choice

3. 包管理器选择

4. Run the Scaffold

4. 运行脚手架

5. Configure
`.env`

5. 配置
`.env`

6. Database Setup

6. 数据库设置

7. Run Migrations

7. 执行数据库迁移

8. AI Capabilities — Opt-in

8. AI功能——可选启用

9. Authentication — Inform, Don't Configure

9. 认证——告知即可，无需配置

9b. Production Extras — Opt-in (Single Multi-Select)

9b. 生产环境附加功能——可选启用（多选）

10. Verify the Build

10. 验证构建

11. Start the Dev Server and Verify

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

12. Report Success

12. 报告成功

Publishing Note

发布说明

create-agentic-app

Original

Translation

Create Agentic App

Create Agentic App

1. Pre-flight Checks

1. 预检检查

2. Folder Strategy

2. 文件夹策略

2a. Empty or git-only cwd

2a. 当前目录为空或仅包含.git文件夹

2b. Non-empty cwd

2b. 当前目录非空

3. Package-Manager Choice

3. 包管理器选择

4. Run the Scaffold

4. 运行脚手架

5. Configure .env

5. 配置.env

6. Database Setup

6. 数据库设置

7. Run Migrations

7. 执行数据库迁移

8. AI Capabilities — Opt-in

8. AI功能——可选启用

9. Authentication — Inform, Don't Configure

9. 认证——告知即可，无需配置

9b. Production Extras — Opt-in (Single Multi-Select)

9b. 生产环境附加功能——可选启用（多选）

10. Verify the Build

10. 验证构建

11. Start the Dev Server and Verify

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

12. Report Success

12. 报告成功

Publishing Note

发布说明

5. Configure
`.env`

5. 配置
`.env`