Initialize an Adobe App Builder project end-to-end and prepare the machine to build one. Creates the Console project and workspace, subscribes APIs (including those needing a product profile), maps intent to the right template, runs non-interactive `aio app init`, and guides post-init customization. Use whenever the user mentions creating an App Builder app, scaffolding a project, `aio app init`, an Experience Cloud extension, adding actions or web assets, or creating a Console project/workspace — even without saying "App Builder". Also for SPA templates, AEM extensions, API Mesh, Asset Compute workers, and MCP servers. Also covers first-time machine/CLI setup (Node 20, aio CLI install, `aio login`, IMS org, stage vs prod) and debugging setup/init failures — `ERR_REQUIRE_ESM`, empty `aio console org list`, `451 accept developer terms`, template not found, init hangs, or Node/npm and post-init build errors.
Instrucciones de origen · Vista previa de solo lectura
name
appbuilder-project-init
description
Initialize an Adobe App Builder project end-to-end and prepare the machine to build one. Creates the Console project and workspace, subscribes APIs (including those needing a product profile), maps intent to the right template, runs non-interactive `aio app init`, and guides post-init customization. Use whenever the user mentions creating an App Builder app, scaffolding a project, `aio app init`, an Experience Cloud extension, adding actions or web assets, or creating a Console project/workspace — even without saying "App Builder". Also for SPA templates, AEM extensions, API Mesh, Asset Compute workers, and MCP servers. Also covers first-time machine/CLI setup (Node 20, aio CLI install, `aio login`, IMS org, stage vs prod) and debugging setup/init failures — `ERR_REQUIRE_ESM`, empty `aio console org list`, `451 accept developer terms`, template not found, init hangs, or Node/npm and post-init build errors.
metadata
{"category":"project-initialization"}
license
Apache-2.0
compatibility
Requires aio CLI (Adobe I/O CLI) — install or refresh with `npm install -g @adobe/aio-cli` so the bundled plugins (`aio-cli-plugin-console`, `aio-cli-plugin-app`, etc.) are current. Node.js 18+ (Node 24 supported on Stage runtimes). Bash shell.
allowed-tools
Bash(aio:*) Bash(npm:*) Bash(node:*) Read Write
App Builder Project Initialization
Maps user intent to the right Adobe App Builder template and runs non-interactive aio app init. Default: @adobe/generator-app-excshell (SPA + actions). For headless/bare projects, use init-bare.
When a Developer Console project / workspace / API subscription does not yet exist, this skill walks the agent through creating them non-interactively by calling aio console … directly — see the Bootstrap section and references/bootstrap.md. The latest @adobe/aio-cli bundle exposes non-interactive aio console project create / workspace create / api list / workspace api add (with --license-config for services that require a product profile), and non-interactive aio app init --org/--project/--template-options. Together they remove every blocking "open the Developer Console UI and click" step from the agentic setup path. Just install the latest CLI (npm install -g @adobe/aio-cli) and use them.
Machine setup (first time)
Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to Bootstrap below.
Have nvm?nvm install 20 && nvm use 20 && nvm alias default 20 so new shells keep it. If several Node versions are installed, the active one must be 20.
No Node / no nvm? Install nvm, then Node 20:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# reopen the shell, then:
nvm install 20 && nvm use 20 && nvm alias default 20
(Alternatives: brew install node@20, or the official installer at nodejs.org.)
Older Adobe docs say Node 18 — use 20. A global aio belongs to whichever Node was active when you ran npm i -g; if you switch Node versions the old aio won't be on PATH. Symptom of a mismatch: aio dies with (a pre-20 Node parsing the Node-20 ) — fix with and reinstall there.
SyntaxError: Unexpected token '??='
aio
nvm use 20
aio
2. Install the aio CLI + log in
npm install -g @adobe/aio-cli # on Node 20
aio login # opens a browser; `aio login -f` forces a fresh prompt
aio where# confirm the correct IMS org/context
aio console org list # list orgs and their IDs (then `aio console org select <id>` if needed)
Tokens are stored by the CLI automatically; a normal aio login lasts hours/days — one login per session, not per command. Confirm the correct IMS org — wrong-org is the most common setup mistake.
3. Stage vs prod
The default environment is prod. To target stage, set the env var and re-authenticate:
export AIO_CLI_ENV=stage
aio logout && aio login
Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console (developer-stage).
Logging in without a browser (CI / no human)
Import creds: in the Developer Console open the workspace → Download all → console.json, then aio app init <app> --import path/to/console.json (fills .env/.aio — treat console.json as a secret, gitignore it).
CI / pipeline: add an OAuth Server-to-Server credential to the workspace; aio and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly.
Bootstrap the Developer Console (project, workspace, APIs)
If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state beforeaio app init. Otherwise aio app init / aio app use / aio app deploy have nothing to wire the local app to.
The full bootstrap is just aio commands; call them directly, not through a wrapper script. They are already non-interactive in the recent plugin releases, and per-step calls let you react to "already exists" or "needs a product profile" responses without baking those decisions into bash.
Preflight
Make sure the CLI is current — that's what brings in the non-interactive Console + app init commands:
npm install -g @adobe/aio-cli
aio --version
Don't try to assert specific plugin versions; just take the latest. If a console or app subcommand below is rejected as "command not found" or "unknown flag" after this, the CLI install genuinely failed (PATH issue, permissions, registry mirror) — fix the install rather than working around it.
Confirm an org is selected (or pass --orgId on every command below):
aio console org list --json # if needed, then:
aio console org select <orgId>
Decision rule
User state
Next action
"Create a project + workspace + add APIs from scratch"
Run the bootstrap chain (project → workspace → APIs), then aio app init.
Project exists, workspace missing
Skip project-create. Run aio console workspace create, then optionally aio console workspace api add.
Project + workspace exist, only need to add an API
Run aio console api list to discover service codes, then aio console workspace api add.
Everything already wired
Skip bootstrap. Go straight to Initialize via Script.
Always check what already exists with aio console project list --json and aio console workspace api list --projectName <p> --workspaceName <w> --json before creating — these commands fail loudly on "already exists" and there is no built-in idempotency.
Step 2 — create a workspace inside it (Stage is the conventional first non-Production workspace; pick a more descriptive name in long-lived shared projects):
Step 3 — discover and subscribe the APIs the app needs:
aio console api list --json # see all service codes available to the org# entries flagged for whether they need a product profile# Free-tier service:
aio console workspace api add \
--projectName my-project \
--workspaceName Stage \
--service-code AdobeIOManagementAPISDK \
--json
# Service that requires a product profile:
aio console workspace api add \
--projectName my-project \
--workspaceName Stage \
--service-code AdobeAnalyticsSDK \
--license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \
--json
--service-code accepts a comma-separated list to subscribe several free-tier services in one call. --license-config is repeatable when several profile-bound services are added together.
Recover from per-step failures
Failure
What to do
project create fails with "already exists"
Read aio console project list --json, reuse the existing project's name, and continue at step 2.
workspace create fails with "already exists"
List workspaces with aio console workspace list --projectName <p> --json and continue at step 3.
workspace api add returns "product profile required"
The service code requires --license-config. Ask the user (or the org admin) for the profile name and retry with --license-config CODE=PROFILE.
Any step returns an org-selection error
Pass --orgId <id> explicitly, or aio console org select <id> once before retrying.
Wire the local app to the bootstrapped state
Two equivalent ways to point a fresh aio app init at the project/workspace you just created:
The wrapper passes --org / --project / --template-options straight through to aio app init, on top of the existing -y --no-login --no-install flags.
Run aio app use after init (works on any plugin version):
cd ./my-project
aio app use --no-input # adopts the currently selected project/workspace, no prompts
Either route ends with the local .aio and .env pointing at the workspace you just bootstrapped, so aio app deploy publishes to the right namespace.
Fast Path (for clear requests)
When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to Initialize via Script below. Use the matched template and any project name the user provided (or a sensible default).
Examples of fast-path triggers:
"Create an App Builder app using @adobe/generator-app-excshell" → use that template, run init
"Set up an Asset Compute worker" → maps unambiguously to @adobe/generator-app-asset-compute, run init
"Create a new App Builder app" (no specifics) → defaults to @adobe/generator-app-excshell, run init
"Initialize a bare project" → use init-bare, run init
If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below.
Template Decision Table
Pick the template that matches the user's intent. When unclear, default to @adobe/generator-app-excshell.
User wants
Template
SPA with actions + React UI
@adobe/generator-app-excshell
AEM Content Fragment Console extension
@adobe/aem-cf-admin-ui-ext-tpl
AEM React SPA (WKND-based)
@adobe/generator-app-aem-react
Adobe API Mesh (GraphQL)
@adobe/generator-app-api-mesh
Asset Compute custom worker
@adobe/generator-app-asset-compute
Remote server on App Builder
@adobe/generator-app-remote-mcp-server-generic
Bare / from-scratch project (no pre-scaffolded actions or UI)
init.sh init-bare
For a headless/backend-only request, prefer init-bare when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no web-src frontend directory or web manifest wiring.
Initialize via Script
The aio app * wrappers go through a single script: scripts/init.sh. (Console bootstrap commands are called directly — see the Bootstrap section above for the rationale.)
Note: The path to this skill's scripts may be skills/, .augment/skills/, or .github/skills/ depending on your platform and repository layout. Adjust the prefix in the commands below accordingly.
--org, --project, --template-options (base64-encoded JSON), and --no-config-validation are passed straight through to aio app init. Use the latest @adobe/aio-cli so they're all recognised; --no-config-validation is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation.
Use init-bare only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal:
app.config.yaml exists with an empty or minimal application.runtimeManifest
package.json exists with only the basic project dependencies
No pre-scaffolded src/, web-src/, or actions/ directories
Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested.
The script outputs JSON with success, path, and output fields. Check success before proceeding.
Full Workflow (for ambiguous or complex requests)
Step 1 — Gather intent
Ask the user (or infer from conversation context):
Question
Examples
What type of app?
SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server
Needs a UI?
Yes (React Spectrum in ExC Shell), No (actions only)
Extension point?
dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A
Additional actions?
Names and purposes of custom actions beyond the default
Console state?
Existing project + workspace? Or do we need to create them and subscribe APIs first?
APIs needed?
e.g. Adobe I/O Management, Analytics, Target — including any that require a product profile
If the user simply says "create an App Builder app" with no specifics, default to @adobe/generator-app-excshell.
If the Console state is "from scratch" or unknown, run the Bootstrap the Developer Console flow before continuing to template selection. See references/bootstrap.md for the full agentic bootstrap playbook.
Step 2 — Select template
Consult the Template Decision Table above and references/templates.md to map the user's intent to a template.
Step 3 — Initialize, customize, validate
Follow the Initialize via Script, Post-init customization, and Validate sections below.
Install dependencies — Run npm install in the project directory. The init script uses --no-install to keep initialization fast, but dependencies are required before building or testing.
For API Mesh projects, verify mesh.json is at the project root — After aio app init with @adobe/generator-app-api-mesh, confirm ./mesh.json exists before treating the scaffold as ready. If the file only exists at node_modules/@adobe/generator-app-api-mesh/templates/mesh.json, copy it into place with cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json. The file under node_modules/ is the generator's template source, not the project's active API Mesh configuration. Then customize the root mesh.json with the user's real source handlers; for multi-backend scenarios, configure at least two handlers.
Clean up bare-project scaffolding if needed — After init-bare, inspect the generated project. If the initializer created actions/, src/, or web-src/, remove those directories before continuing. A bare project should not keep auto-generated action code or web assets.
Headless cleanup after template init — If the user wants a headless project with no frontend, delete any generated UI directory after aio app init: rm -rf web-src/ or the template-specific path such as rm -rf src/<extension>/web-src/. Then remove matching web-src config from app.config.yaml or ext.config.yaml if present, especially web: web-src and operations.view / impl: index.html entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project.
Add actions — If the user later wants custom actions, run cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action".
Add web assets — Only if the user later decides the bare project needs a UI, run skills/appbuilder-project-init/scripts/init.sh add-web-assets.
Set runtime: nodejs:22 for production. Stage workspaces also accept runtime: nodejs:24.
Add inputs: for environment variables the action needs
Set annotations.require-adobe-auth: true if the action needs IMS tokens
Set web: 'yes' or web: 'raw' depending on HTTP access needs
Edit app.config.yaml — For multi-extension projects, add $include entries.
Apply action boilerplate — Use the appbuilder-action-scaffolder skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling.
Validate
Verify the project structure by checking these items directly:
app.config.yaml** exists** and contains valid YAML
All $include paths resolve to real files
ext.config.yaml (if present) has runtimeManifest.packages with at least one action
Action JS files exist at all declared function: paths
package.json** exists** with name, version, and an Adobe SDK dependency (@adobe/aio-sdk or @adobe/aio-lib-core-logging)
**No root-level **runtimeManifest in app.config.yaml (see Manifest guardrail below)
Read the relevant files and verify each check. Fix any issues before proceeding.
Build, Test, Deploy (optional)
If the user wants to go beyond scaffolding:
aio app build # Build
aio app test# Run tests
aio app deploy # Deploy to Adobe I/O Runtime
aio app dev # Run locally for development (use `aio app run` instead if actions use State SDK, Files SDK, or sequences)
Manifest guardrail
Extension projects: Actions are defined under runtimeManifest in ext.config.yaml, referenced via $include from app.config.yaml.
Standalone apps: Actions go under application.runtimeManifest in app.config.yaml.
Do not place a root-level runtimeManifest directly in app.config.yaml: the CLI ignores those actions, so they will not deploy. If you see this shape, move it under application.runtimeManifest or into ext.config.yaml.
Troubleshooting & Edge Cases
aio** CLI not installed:** If aio --version returns command not found or fails, stop before initialization. Ask the user to install Adobe I/O CLI, complete aio auth login, and retry only after the CLI is available.
npm install** fails after init:** The scaffold can still be created because init runs with --no-install, but builds/tests will fail until dependencies install cleanly. Capture the first package error, confirm the Node/npm version is compatible, rerun npm install from the project root, and only continue once it succeeds.
Template choice is ambiguous: If the request could map to multiple templates, ask one clarifying question about UI vs headless, extension point, or target Adobe product. If the user has no preference, default to @adobe/generator-app-excshell and state that assumption explicitly.
Project directory already exists or is not empty: Do not overwrite it silently. Ask whether to use a different directory, clear the existing folder, or initialize into a new path.
aio console …** subcommand or flag not recognised:** Almost always means the CLI bundle is stale. Run npm install -g @adobe/aio-cli and retry — that's the supported way to refresh every plugin (console, app, runtime, ims-oauth, telemetry). Only dig deeper if the same command still fails after a clean reinstall.
Workspace API add fails with "product profile required": The service code needs a product profile. Re-run aio console api list --json to confirm, ask the user (or org admin) for the profile name, and retry with --license-config CODE=PROFILE.
No org selected: Console bootstrap commands will fail with an org-selection error. Run aio console org list then aio console org select <orgId> (or pass --orgId to every command) before retrying.
Validation errors from a freshly scaffolded but partially edited project: Recent aio app * versions validate app.config.yaml by default against an OpenWhisk-aligned schema. The validation runs on every aio app * command that reads or writes the manifest — concretely: aio app init, aio app add (action|web-assets|extension|event|service), aio app delete (action|web-assets|extension|event|service), aio app build, aio app deploy, aio app undeploy, aio app run, aio app dev, aio app use, and aio app info. The escape hatch flag is the same on all of them: --no-config-validation. Use it on the single command you need to unblock (e.g. aio app build --no-config-validation while you're still mid-refactor), then drop it as soon as the manifest is whole. Don't bake it into scripts — silent drift between local config and the deployed shape is exactly what the validator was added to catch.
Template listing hangs behind a corporate proxy: Older CLI bundles didn't honour HTTP_PROXY / HTTPS_PROXY during the template registry SSL handshake. Run npm install -g @adobe/aio-cli to pick up the proxy fix, confirm HTTPS_PROXY is exported in the same shell, and retry.
aio** commands die instantly with ERR_REQUIRE_ESM (exit 127):** A clean install can resolve @adobe/aio-cli-plugin-certificate to 2.2.0 (shipped as ESM), which the bundled CommonJS console lib cannot require() — every aio where / login / console command exits 127 with [ERR_REQUIRE_ESM] (though aio -v still prints a version, which is misleading). Pin the plugin to the last CommonJS 2.x inside the global package: cd "$(npm root -g)/@adobe/aio-cli" && npm install @adobe/aio-cli-plugin-certificate@2.1.0. Re-check after any aio update.
aio console org list** returns nothing / []:** Login succeeded but the org list is empty — almost always the wrong environment (internal Adobe/App Builder dev lives on stage, but the CLI defaults to prod). Switch: export AIO_CLI_ENV=stage && aio logout && aio login. If stage is also empty, it's an entitlement problem, not an environment one (needs an App Builder license and the user added under Admin Console → Users → Developers).
aio console project list** → 451 … accept developer terms:** The org's Adobe Developer Terms of Use haven't been accepted — a one-time, per-org acceptance the CLI can't do for you. Open the Developer Console (Stage https://developer-stage.adobe.com/console, Prod https://developer.adobe.com/console), confirm the correct org (top-right), accept the prompt, then re-run the command.
Chaining with other skills
After initialization, hand off to:
appbuilder-action-scaffolder — For scaffolding actions with playbook, checklist, boilerplate templates, and manifest validation
appbuilder-ui-scaffolder — Build React Spectrum UI for ExC Shell SPAs and AEM extensions
references/bootstrap.md — Agentic Developer Console bootstrap (project, workspace, API subscriptions) via raw aio console … commands from the latest @adobe/aio-cli
references/templates.md — Template catalog with intent mapping and per-template post-init guidance
references/debugging.md — Troubleshooting guide for init failures, Node/npm issues, login problems, and first-run errors
