next-campaigns-setup
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese/next-campaigns-setup: Scaffold + Configure a New CPK Campaign
/next-campaigns-setup:搭建并配置新的CPK活动
Using This Skill
使用此技能
This skill works with any AI coding tool that can load a markdown file as context.
| Tool | How to Use |
|---|---|
| Claude Code | Install to |
| OpenAI Codex | Pass as a system prompt: |
| Cursor | Add to |
| GitHub Copilot | Add to |
| Other agents | Load |
Scaffold and configure a new campaign-page-kit campaign in one pass.
Boundary with other campaign skills:
- Use this skill for repo/project bootstrap: brand folder, page-kit init, starter template copy, ,
campaigns.json, and first config values.CLAUDE.md - Use when a CampaignSpec/design exists and pages need to be wired end-to-end from spec/API/design into page-kit.
next-campaigns-build - Use for CampaignSpec lifecycle work: map inspection, multi-funnel planning, QA results, Linear/run-through orchestration, promotion decisions, and split-test config.
next-campaigns-os - This skill may consume a CampaignSpec if one is provided, but it should not try to replace the build skill's page wiring or the OS skill's lifecycle decisions.
本技能可与任何能加载markdown文件作为上下文的AI编码工具配合使用。
| 工具 | 使用方法 |
|---|---|
| Claude Code | 安装至 |
| OpenAI Codex | 作为系统提示传入: |
| Cursor | 添加至 |
| GitHub Copilot | 添加至 |
| 其他Agent | 将 |
一次性搭建并配置新的Campaign-Page-Kit活动。
与其他活动技能的边界:
- 使用本技能完成仓库/项目初始化:品牌文件夹、page-kit初始化、启动模板复制、、
campaigns.json及初始配置值。CLAUDE.md - 当CampaignSpec/设计已存在,需要将页面从规格/API/设计端到端接入page-kit时,使用。
next-campaigns-build - 处理CampaignSpec生命周期工作(映射检查、多漏斗规划、QA结果、Linear/流程编排、推广决策、拆分测试配置)时,使用。
next-campaigns-os - 本技能可在提供CampaignSpec的情况下使用,但不应替代build技能的页面接入工作或OS技能的生命周期决策。
Phase 1 — Scaffold
第一阶段 — 搭建框架
Step 0: Resolve CPK Root
步骤0:确定CPK根目录
Check for a environment variable:
CPK_ROOTbash
echo "${CPK_ROOT:-not set}"If not set, ask the user:
What is the path to your CPK project root? (e.g.)/Users/you/projects/my-campaigns
Use this value as for all paths below. Do not hardcode any absolute path.
<CPK_ROOT>检查是否存在环境变量:
CPK_ROOTbash
echo "${CPK_ROOT:-not set}"若未设置,询问用户:
你的CPK项目根目录路径是什么? (例如:)/Users/you/projects/my-campaigns
将此值作为后续所有路径的。请勿硬编码任何绝对路径。
<CPK_ROOT>Step 1: Gather Campaign Details
步骤1:收集活动详情
Ask for all three in a single message — do not ask one at a time:
- Brand name — the client/brand slug. Lowercase, hyphens only. Becomes the brand folder.
- Public route slug — the pretty campaign URL/page-kit folder slug, usually product name + version (e.g. ,
grounding-mat). Lowercase, hyphens only. This is not the Campaign Map Builder Map ID.grounding-mat-v2 - Starter template — which template to base this on:
- — standard single-step checkout
demeter - — single-step checkout (alternate layout)
limos - — single-step checkout (premium layout)
olympus - — single-step with variant/SKU selection
olympus-mv-single-step - — two-step flow: variant picker → checkout
olympus-mv-two-step - — shop-style single-step checkout
shop-single-step - — multi-step checkout (information → shipping → billing)
shop-three-step - — presell/landing page component library (not a checkout funnel; use when building a standalone landing or presell page)
landing
在一条消息中询问以下所有信息——不要逐个询问:
- 品牌名称 — 客户/品牌别名,仅使用小写字母和连字符,将作为品牌文件夹名称。
- 公开路由别名 — 活动的友好URL/page-kit文件夹别名,通常为产品名称+版本(例如:,
grounding-mat),仅使用小写字母和连字符。这不是Campaign Map Builder的Map ID。grounding-mat-v2 - 启动模板 — 选择基于哪个模板:
- — 标准单步结账
demeter - — 单步结账(替代布局)
limos - — 单步结账(高级布局)
olympus - — 带变体/SKU选择的单步流程
olympus-mv-single-step - — 两步流程:变体选择 → 结账
olympus-mv-two-step - — 店铺风格单步结账
shop-single-step - — 多步结账:信息填写 → 配送 → 账单
shop-three-step - — 预售/落地页组件库(非结账漏斗;用于构建独立落地页或预售页时)
landing
Paths
路径说明
- Brand folder:
<CPK_ROOT>/[brand-name]/ - Campaign folder:
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/ - Starter templates repo: (subfolder:
https://github.com/NextCommerceCo/campaign-cart-starter-templates)src/[template-slug]
- 品牌文件夹:
<CPK_ROOT>/[brand-name]/ - 活动文件夹:
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/ - 启动模板仓库: (子文件夹:
https://github.com/NextCommerceCo/campaign-cart-starter-templates)src/[template-slug]
Step 2 — Safety Check
步骤2 — 安全检查
If already exists → stop and warn the user. Do not overwrite.
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/如果已存在 → 停止操作并警告用户,请勿覆盖。
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/Step 3 — Create Brand Folder (if needed)
步骤3 — 创建品牌文件夹(如需要)
If does not exist, create it.
<CPK_ROOT>/[brand-name]/如果不存在,则创建该文件夹。
<CPK_ROOT>/[brand-name]/Step 4 — Initialize CPK Project (if needed)
步骤4 — 初始化CPK项目(如需要)
Check if exists.
<CPK_ROOT>/[brand-name]/package.jsonIf not, run these commands sequentially inside the brand folder:
bash
cd <CPK_ROOT>/[brand-name]
npm init -y
npm install next-campaign-page-kit
npx campaign-initnpx campaign-init_data/campaigns.jsonpackage.jsonsrc/After running, verify it succeeded:
- Check exists — if not, stop and warn the user that
_data/campaigns.jsonmay have failedcampaign-init - Check contains a
package.jsonscript — if not, warn the user to rundevmanuallynpx campaign-init
If already exists, skip — the project is already initialized.
package.json检查是否存在。
<CPK_ROOT>/[brand-name]/package.json若不存在,在品牌文件夹中依次运行以下命令:
bash
cd <CPK_ROOT>/[brand-name]
npm init -y
npm install next-campaign-page-kit
npx campaign-initnpx campaign-init_data/campaigns.jsonpackage.jsonsrc/运行完成后,验证是否成功:
- 检查是否存在——若不存在,停止操作并警告用户
_data/campaigns.json可能执行失败campaign-init - 检查是否包含
package.json脚本——若不存在,警告用户手动运行devnpx campaign-init
若已存在,则跳过此步骤——项目已完成初始化。
package.jsonStep 5 — Copy Starter Template
步骤5 — 复制启动模板
Before copying, confirm the template slug is valid. Valid slugs are:
, , , , , , ,
demeterlimosolympusolympus-mv-single-stepolympus-mv-two-stepshop-single-stepshop-three-steplandingIf the provided template slug is not in this list → stop and ask the user to pick a valid template.
Run from the brand folder:
bash
cd <CPK_ROOT>/[brand-name]
npx degit NextCommerceCo/campaign-cart-starter-templates/src/[template-slug] src/[campaign-slug]If degit exits with a non-zero code or reports that the source path was not found, stop and warn the user — the template slug may not exist in the upstream repo.
After degit completes (even with exit code 0), verify the directory is not empty:
bash
[ "$(ls -A src/[campaign-slug])" ] || echo "EMPTY"If the output is , stop and warn the user — degit returned success but extracted nothing. This can happen when the subfolder path is wrong or a GitHub cache issue occurred. Do not continue to Phase 2.
EMPTY复制前,确认模板别名有效。有效别名包括:
, , , , , , ,
demeterlimosolympusolympus-mv-single-stepolympus-mv-two-stepshop-single-stepshop-three-steplanding若提供的模板别名不在此列表中 → 停止操作并要求用户选择有效模板。
在品牌文件夹中运行:
bash
cd <CPK_ROOT>/[brand-name]
npx degit NextCommerceCo/campaign-cart-starter-templates/src/[template-slug] src/[campaign-slug]若degit返回非零代码或报告源路径不存在,停止操作并警告用户——模板别名可能在上游仓库中不存在。
degit完成后(即使返回0),验证目录是否非空:
bash
[ "$(ls -A src/[campaign-slug])" ] || echo "EMPTY"若输出为,停止操作并警告用户——degit返回成功但未提取任何内容,这可能是子文件夹路径错误或GitHub缓存问题导致。请勿进入第二阶段。
EMPTYStep 6 — Fetch the Template's campaigns.json Entry
步骤6 — 获取模板的campaigns.json条目
Fetch the upstream campaigns.json to get the canonical entry for the chosen template:
https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/HEAD/_data/campaigns.jsonIf the fetch fails or returns non-JSON, stop and warn the user.
Find the entry matching . Note: the folder is keyed as in the upstream campaigns.json — look up when that template is chosen. For all other templates the key matches the folder name. If no entry is found → stop and warn the user. Use its , , and field structure as the base. Then customise:
[template-slug]olympus-mv-single-stepolympus-mv-singleolympus-mv-singlesdk_versiondescription- Key: change from to
[template-slug][campaign-slug] - : title-case derived from the public route slug (hyphens → spaces)
name - ,
store_name,store_url,store_terms,store_privacy,store_contact,store_returns: set tostore_shipping"" - ,
store_phone: set tostore_phone_tel"" - : keep as it appears in the upstream entry (typically
entry_urlfor checkout funnels)"presell" - ,
gtm_id: set tofb_pixel_idunless real values are provided later. Do not preserve placeholder pixel/container IDs from the template."" - : keep exactly as it appears in the upstream entry — do not hardcode
sdk_version
Merge this entry into — do not replace the whole file.
<CPK_ROOT>/[brand-name]/_data/campaigns.json获取上游的campaigns.json以获取所选模板的标准条目:
https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/HEAD/_data/campaigns.json若获取失败或返回非JSON内容,停止操作并警告用户。
找到与匹配的条目。注意:文件夹在上游campaigns.json中的键为——选择该模板时需查找。其他模板的键均与文件夹名称一致。若未找到对应条目 → 停止操作并警告用户。以其、和字段结构为基础进行自定义:
[template-slug]olympus-mv-single-stepolympus-mv-singleolympus-mv-singlesdk_versiondescription- 键:从改为
[template-slug][campaign-slug] - :由公开路由别名转换为标题格式(连字符替换为空格)
name - ,
store_name,store_url,store_terms,store_privacy,store_contact,store_returns:设置为store_shipping"" - ,
store_phone:设置为store_phone_tel"" - :保留上游条目中的内容(结账漏斗通常为
entry_url)"presell" - ,
gtm_id:设置为fb_pixel_id,除非后续提供真实值。请勿保留模板中的占位符像素/容器ID。"" - :完全保留上游条目中的值——请勿硬编码
sdk_version
将此条目合并到中——请勿替换整个文件。
<CPK_ROOT>/[brand-name]/_data/campaigns.jsonStep 7 — Copy CLAUDE.md
步骤7 — 复制CLAUDE.md
Download and save the AI context file into the brand project root as :
CLAUDE.mdbash
curl -sL "https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/HEAD/docs/campaign-page-kit-template-context.md" \
-o <CPK_ROOT>/[brand-name]/CLAUDE.mdIf already exists in the brand folder, skip — do not overwrite.
CLAUDE.md下载AI上下文文件并保存到品牌项目根目录,命名为:
CLAUDE.mdbash
curl -sL "https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/HEAD/docs/campaign-page-kit-template-context.md" \
-o <CPK_ROOT>/[brand-name]/CLAUDE.md若品牌文件夹中已存在,则跳过此步骤——请勿覆盖。
CLAUDE.mdPhase 2 — Configure
第二阶段 — 配置
Step 8 — Gather Config Inputs
步骤8 — 收集配置输入
Ask for all of the following in a single message — do not ask one at a time:
If the user supplied a CampaignSpec, pre-fill from:
- for store name when present
campaign.store_name - for the public route slug when present
campaign.slug - for the report/provenance only; never use the Map ID as the page-kit folder unless the user explicitly asks
spec_identity.map_id - for analytics intent
campaign.tracking - for policy/support URLs
campaign.footer_links[] - for later build/QA notes only; setup does not need to write SEO tags directly
campaign.seo
Required:
- API key — the Campaign Cart API key for this store
- Store name — short display name (e.g. "Winter Gloves Co")
- Store URL — the main store domain (e.g. )
https://wintergloves.com
Recommended but optional:
- Store phone — display format (e.g. ) and tel format (e.g.
1-800-555-0100)+18005550100 - Policy/support URLs — terms, privacy, contact, returns/refund, shipping. Storefront policy URLs are acceptable; campaign-specific pages are not required.
Validate all URLs before writing any files:
- Each provided URL must start with and contain at least one
https://after the domain. - If an optional URL is absent, write for that field rather than inventing a placeholder
"" - If any provided URL fails this check, show which ones are invalid and ask the user to correct or omit them before proceeding. Do not write partial data.
Optional tracking contract:
- Tracking status — ,
unknown,not_configured, orconfiguredcustom_required - GTM container ID — e.g.
GTM-XXXXXXX - Facebook Pixel ID — e.g.
123456789012345 - Custom analytics endpoint or notes — record in the report unless the template config already supports a matching custom analytics provider
Do not make the user guess through a wall of tracking surfaces. Ask for GTM/Facebook/custom only when they already have values or the CampaignSpec declares them. If tracking is or , leave provider IDs blank/disabled and record that tracking is intentionally not configured yet.
unknownnot_configured在一条消息中询问以下所有信息——不要逐个询问:
若用户提供了CampaignSpec,从以下字段预填充:
- 若存在,则预填充店铺名称
campaign.store_name - 若存在,则预填充公开路由别名
campaign.slug - 仅用于报告/溯源;除非用户明确要求,否则请勿将Map ID用作page-kit文件夹名称
spec_identity.map_id - 用于分析意图
campaign.tracking - 用于政策/支持URL
campaign.footer_links[] - 仅用于后续构建/QA备注;设置阶段无需直接编写SEO标签
campaign.seo
必填项:
- API密钥 — 此店铺的Campaign Cart API密钥
- 店铺名称 — 简短显示名称(例如:"Winter Gloves Co")
- 店铺URL — 主店铺域名(例如:)
https://wintergloves.com
推荐但可选:
- 店铺电话 — 显示格式(例如:)和tel格式(例如:
1-800-555-0100)+18005550100 - 政策/支持URL — 条款、隐私、联系、退换货、配送。可使用店铺端的政策URL;无需使用活动专属页面。
写入文件前验证所有URL:
- 每个提供的URL必须以开头,且域名后至少包含一个
https://. - 若可选URL未提供,对应字段写入,而非生成占位符
"" - 若任何提供的URL不符合检查要求,告知用户哪些URL无效,要求用户修正或忽略后再继续。请勿写入不完整数据。
可选跟踪配置:
- 跟踪状态 — ,
unknown,not_configured, 或configuredcustom_required - GTM容器ID — 例如:
GTM-XXXXXXX - Facebook Pixel ID — 例如:
123456789012345 - 自定义分析端点或备注 — 记录在报告中,除非模板配置已支持匹配的自定义分析提供商
不要让用户在众多跟踪选项中猜测。仅当用户已有对应值或CampaignSpec中声明时,才询问GTM/Facebook/自定义跟踪信息。若跟踪状态为或,保持GTM/Facebook禁用或为空。若模板中包含占位符ID,需移除。
unknownnot_configuredStep 9 — Update config.js
步骤9 — 更新config.js
Read . Make these changes:
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/assets/config.js- — replace the placeholder value with the provided API key
apiKey - — replace with a lowercase-hyphenated slug derived from the store name (e.g. "Winter Gloves Co" →
storeName). This is an analytics identifier, not a display name.'winter-gloves-co' - GTM (only if a real ID is provided):
- Set to
gtm.enabledtrue - Set to the provided ID
gtm.settings.containerId
- Set
- Facebook Pixel (only if a real ID is provided):
- Set to
facebook.enabledtrue - Set to the provided ID
facebook.settings.pixelId
- Set
- Absent tracking:
- If tracking status is or
unknown, keep GTM/Facebook disabled or blank. Remove obvious placeholder IDs if the template copied them.not_configured - If tracking status is , do not invent custom event wiring here; report it as a follow-up for
custom_required.next-campaigns-build
- If tracking status is
Do not change any other fields. Preserve all comments.
读取,进行以下修改:
<CPK_ROOT>/[brand-name]/src/[campaign-slug]/assets/config.js- — 用提供的API密钥替换占位符值
apiKey - — 由店铺名称转换为小写连字符格式(例如:"Winter Gloves Co" →
storeName)。这是分析标识符,而非显示名称。'winter-gloves-co' - GTM(仅当提供真实ID时):
- 将设置为
gtm.enabledtrue - 将设置为提供的ID
gtm.settings.containerId
- 将
- Facebook Pixel(仅当提供真实ID时):
- 将设置为
facebook.enabledtrue - 将设置为提供的ID
facebook.settings.pixelId
- 将
- 无跟踪配置:
- 若跟踪状态为或
unknown,保持GTM/Facebook禁用或为空。若模板中包含明显的占位符ID,需移除。not_configured - 若跟踪状态为,请勿在此处创建自定义事件接入;将其记录为后续
custom_required的待办事项。next-campaigns-build
- 若跟踪状态为
请勿修改其他字段,保留所有注释。
Step 10 — Update campaigns.json
步骤10 — 更新campaigns.json
Read . Find the entry with key matching . If the entry is missing, stop and warn the user — Phase 1 may not have completed successfully.
<CPK_ROOT>/[brand-name]/_data/campaigns.json[campaign-slug]Update these fields:
- → provided store name
store_name - → provided store URL
store_url - → provided phone display format, or
store_phone"" - → provided phone tel format, or
store_phone_tel"" - → provided terms URL, or
store_terms"" - → provided privacy URL, or
store_privacy"" - → provided contact URL, or
store_contact"" - → provided returns URL, or
store_returns"" - → provided shipping URL, or
store_shipping"" - → provided GTM ID, or
gtm_id"" - → provided pixel ID, or
fb_pixel_id""
Do not change any other fields in the file.
读取,找到键与匹配的条目。若条目缺失,停止操作并警告用户——第一阶段可能未完成。
<CPK_ROOT>/[brand-name]/_data/campaigns.json[campaign-slug]更新以下字段:
- → 提供的店铺名称
store_name - → 提供的店铺URL
store_url - → 提供的电话显示格式,或
store_phone"" - → 提供的电话tel格式,或
store_phone_tel"" - → 提供的条款URL,或
store_terms"" - → 提供的隐私URL,或
store_privacy"" - → 提供的联系URL,或
store_contact"" - → 提供的退换货URL,或
store_returns"" - → 提供的配送URL,或
store_shipping"" - → 提供的GTM ID,或
gtm_id"" - → 提供的Pixel ID,或
fb_pixel_id""
请勿修改文件中的其他字段。
Report Back
反馈报告
Summarise everything done:
Phase 1 — Scaffold
✓ Brand folder: created / already existed
✓ CPK project: initialized / already present
✓ Template copied: [template-slug] → src/[campaign-slug]/
✓ campaigns.json seeded (sdk_version: [version])
✓ CLAUDE.md: copied / already present
Phase 2 — Configure
provenance
✓ Map ID: [map-id] / not provided
✓ public route slug: [campaign-slug]
config.js
✓ apiKey set
✓ storeName set to '[value]'
✓ GTM enabled with real ID / left disabled
✓ Facebook Pixel enabled with real ID / left disabled
✓ Tracking status: unknown / not_configured / configured / custom_required
campaigns.json ([campaign-slug])
✓ store_name and store_url set
✓ phone set / left blank
✓ policy/support URLs set / left blankThen show next steps:
Next steps:
1. npm run dev → pick [campaign-slug] and verify the page loads + SDK initialises
2. Check the Campaigns app → confirm the API key is valid for this store
3. npm run config → alternative interactive config editor if you need to adjust settings later
4. QA checklist: check the SDK QA checklist in docs/Dev server preview URLs for the chosen template:
| Template | Pages |
|---|---|
| demeter | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| limos | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| olympus | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| olympus-mv-single-step | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell-mv/ · /[slug]/receipt/ |
| olympus-mv-two-step | /[slug]/presell/ · /[slug]/select/ · /[slug]/checkout/ · /[slug]/upsell-mv/ · /[slug]/receipt/ |
| shop-single-step | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| shop-three-step | /[slug]/presell/ · /[slug]/information/ · /[slug]/shipping/ · /[slug]/billing/ · /[slug]/upsell/ · /[slug]/receipt/ |
| landing | /[slug]/landing/ (component library — no checkout funnel) |
总结已完成的所有操作:
第一阶段 — 搭建框架
✓ 品牌文件夹:已创建 / 已存在
✓ CPK项目:已初始化 / 已存在
✓ 模板已复制:[template-slug] → src/[campaign-slug]/
✓ campaigns.json已初始化(sdk_version: [version])
✓ CLAUDE.md:已复制 / 已存在
第二阶段 — 配置
溯源信息
✓ Map ID:[map-id] / 未提供
✓ 公开路由别名:[campaign-slug]
config.js
✓ apiKey已设置
✓ storeName已设置为'[value]'
✓ GTM已启用(使用真实ID)/ 保持禁用
✓ Facebook Pixel已启用(使用真实ID)/ 保持禁用
✓ 跟踪状态:unknown / not_configured / configured / custom_required
campaigns.json ([campaign-slug])
✓ store_name和store_url已设置
✓ 电话已设置 / 留空
✓ 政策/支持URL已设置 / 留空然后展示后续步骤:
后续步骤:
1. npm run dev → 选择[campaign-slug]并验证页面加载+SDK初始化
2. 检查Campaigns应用 → 确认API密钥对该店铺有效
3. npm run config → 后续如需调整设置,可使用此交互式配置编辑器
4. QA检查清单:查看docs/中的SDK QA检查清单所选模板的开发服务器预览URL:
| 模板 | 页面 |
|---|---|
| demeter | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| limos | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| olympus | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| olympus-mv-single-step | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell-mv/ · /[slug]/receipt/ |
| olympus-mv-two-step | /[slug]/presell/ · /[slug]/select/ · /[slug]/checkout/ · /[slug]/upsell-mv/ · /[slug]/receipt/ |
| shop-single-step | /[slug]/presell/ · /[slug]/checkout/ · /[slug]/upsell/ · /[slug]/receipt/ |
| shop-three-step | /[slug]/presell/ · /[slug]/information/ · /[slug]/shipping/ · /[slug]/billing/ · /[slug]/upsell/ · /[slug]/receipt/ |
| landing | /[slug]/landing/(组件库——无结账漏斗) |