commerce-app-init — Claude Code skill: scaffold a Commerce app
The commerce-app-init skill sets up the base structure and metadata for an Adobe Commerce app. Use it to start a project from scratch or initialize a bare app.
Apache-2.0 342 installs ★ 335 updated 2026-10-24
npx skills add adobe/skills --skill commerce-app-init -a claude-codeWhat commerce-app-init does
The skill writes app.commerce.config.ts at the project root, then runs npx @adobe/aio-commerce-lib-app init to validate the config, install dependencies, and generate project files. You can run it again: user packages in src/commerce-extensibility-1/actions/ are preserved, while generated files under .generated/ are managed by the build.
It finishes by running aio app build to check the configuration. Node.js 22+, the aio CLI, and @adobe/aio-commerce-lib-app are required. This skill does not set up eventing, webhooks, or other extensibility domains. Developer Console setup and deployment need the separate appbuilder-project-init skill.
What it helps with
- scaffold a new Adobe Commerce app
- write app metadata to
app.commerce.config.ts - initialize a bare Commerce project
- validate the app config with a build
Example prompts for the agent
- Create an Adobe Commerce app with the ID
my-commerce-appand scaffold its base project. - Initialize this bare Commerce app and verify it with a build.
- Check the existing
app.commerce.config.tsand generate the project files.
How to install commerce-app-init
1Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-init -a claude-code2Manually: put the files in place
~/.claude/skills/commerce-app-init/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/commerce-app-init/
1Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-init -a codex2Manually: put the files in place
.agents/skills/commerce-app-init/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-init -a cursor2Manually: put the files in place
.cursor/skills/commerce-app-init/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install adobe/skills plugins/commerce/app-management/skills/commerce-app-init2Manually: put the files in place
.github/skills/commerce-app-init/SKILL.md1Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-init -a gemini-cli2Platform CLI
gemini skills install https://github.com/adobe/skills --path plugins/commerce/app-management/skills/commerce-app-initManually: put the files in place
.devin/skills/commerce-app-init/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-init -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about commerce-app-init
How do I install commerce-app-init in Claude Code?
Run npx skills add adobe/skills --skill commerce-app-init -a claude-code. The skill file is installed at ~/.claude/skills/commerce-app-init/SKILL.md.
What does commerce-app-init do?
It creates the Adobe Commerce app config, initializes the project, and checks the result with aio app build.
What does commerce-app-init need to run?
It requires Node.js 22+, the aio CLI, and @adobe/aio-commerce-lib-app. Developer Console setup is handled separately by appbuilder-project-init.
Source text
SKILL.md · Apache-2.0
---
name: commerce-app-init
description: >
Scaffold a new Adobe Commerce app using the aio-commerce-sdk. Creates the base
project structure and app.commerce.config file with metadata. Use when the user
wants to create a new Commerce app from scratch or initialize a bare Commerce
app project. After scaffolding, chains to appbuilder-project-init for Developer
Console setup (project, workspace, API subscriptions) when the user wants to deploy.
Does not configure extensibility domains — use commerce-app-eventing,
commerce-app-webhooks, commerce-app-business-config, commerce-app-admin-ui,
or commerce-app-storage for that.
license: Apache-2.0
compatibility: >
Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
For Developer Console setup (project/workspace creation, API subscriptions, workspace wiring, deploy, or run),
also requires appbuilder-project-init from adobe/skills:
npx skills add adobe/skills --skill appbuilder-project-init -y
metadata:
author: adobe
---
# Initialize a new Commerce App
Scaffolds a bare Adobe Commerce app: creates `app.commerce.config.ts` with metadata,
then runs `init` to install dependencies and generate all required project files.
Extensibility domains (events, webhooks, business config) are added separately via domain skills.
## Step 1 — Create the config
If `app.commerce.config.ts` already exists in the project root, do **not** overwrite it — skip straight to Step 2 (this skill is safe to re-invoke on an app that already has a config). Otherwise, derive values for the following fields from the user's intent, confirm, and write the file to the project root:
```ts
// app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";
export default defineConfig({
metadata: {
id: "my-commerce-app", // alphanumeric + hyphens only, max 100 chars
displayName: "My Commerce App", // shown in App Management UI, max 50 chars
description: "...", // max 255 chars
upgradeMode: "manual", // optional; currently defaults to "manual" while upgrade execution stabilizes (will default to "auto" once ready); "auto" (experimental) runs upgrades after deploy and waits for completion, "manual" returns plans without executing them
version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
},
});
```
See [assets/app.commerce.config.ts](assets/app.commerce.config.ts) for the full annotated template.
## Step 2 — Initialize the project
Always run init — it finds the existing config, validates it, and handles project setup:
```sh
npx @adobe/aio-commerce-lib-app init
```
Since `app.commerce.config.ts` already exists, init skips the interactive prompts. Re-running is safe: when a config is present it installs dependencies and (re)generates the project files — the `app-management` package is regenerated, while user packages under `src/commerce-extensibility-1/actions/` are preserved (see Project structure below).
For a TypeScript Commerce config, init also creates missing `webpack-config.cjs` and root `tsconfig.json` files, installs compatible `typescript`, `ts-loader`, `@tsconfig/bases`, and `@types/node` development dependencies, and adds `typecheck:actions` to the project's composed `typecheck` script. Generated Runtime actions remain JavaScript. Once this scaffolding is in place, user-authored runtime actions (added via the domain skills below) and custom installation scripts (`commerce-app-storage`) can be written in `.ts` — see the [aio-commerce-lib-app usage guide](https://github.com/adobe/aio-commerce-sdk/blob/main/packages/aio-commerce-lib-app/docs/usage.md#setup) for the full migration steps if converting an existing JavaScript project.
### Project structure
After init, the project has two types of directories under `src/`:
- **`src/commerce-extensibility-1/actions/`** — custom runtime actions for webhooks and events. Register them in `src/commerce-extensibility-1/ext.config.yaml` under a user-defined package name (any name except `app-management`, which is reserved by the framework). These survive `aio app build` — the generator only regenerates the `app-management` package.
- **`src/commerce-extensibility-1/.generated/`** — auto-generated by `aio app build`. Treat as read-only; any manual edits here will be overwritten.
- **`src/commerce-configuration-1/`** — managed by `aio app build`. Treat as read-only.
- **Root `tsconfig.json`** — checks the TypeScript Commerce config and generated Runtime actions while excluding Admin UI `web-src`, which has its own TypeScript configuration.
## Step 3 — Verify the config
Build the project to confirm everything is valid:
```sh
aio app build
```
If the config is invalid, the build fails with a detailed validation error pointing to the offending field.
## Common Issues
- **`id` validation error**: `metadata.id` accepts alphanumeric characters and hyphens only — no dots, underscores, or spaces. It cannot change during an upgrade; uninstall and reinstall the app to use a different ID.
- **`version` validation error**: Only numeric semver is accepted (`1.0.0`). Pre-release identifiers (`1.0.0-beta`) are not supported.
- **`defineConfig` not found**: Ensure `@adobe/aio-commerce-lib-app` is installed and imported from `@adobe/aio-commerce-lib-app/config`.
## Quality Bar
- `aio app build` completes without errors
## Chaining
After `aio app build` passes:
1. **Bootstrap the Developer Console** — for any follow-up topic related to App Builder setup (Console project/workspace, API subscriptions, deploy, run, workspace wiring), invoke skill `appbuilder-project-init` (from `adobe/skills`). Tell it:
- Skip the `aio app init` steps — the Commerce scaffold already exists
- Subscribe `AdobeIOManagementAPISDK` (I/O Management API) as part of the workspace bootstrap — required for IMS credential syncing at runtime
- Once the workspace is created, ask the user whether their Commerce backend is **ACCS** (Adobe Commerce as Cloud Service) or **PaaS**. If ACCS, `ACCS-REST-API` must also be subscribed: run `aio console open` to open the workspace in the browser, then add it manually through the Developer Console UI. **Do not proceed until the user confirms it has been added.**
If `appbuilder-project-init` is not installed, ask the user to install it first:
```sh
npx skills add adobe/skills --skill appbuilder-project-init -y
```
2. **Extend with domain skills** — once the workspace is wired:
- `commerce-app-eventing` — manage Commerce and external event sources
- `commerce-app-webhooks` — manage webhook interception
- `commerce-app-business-config` — manage custom business configuration
- `commerce-app-admin-ui` — extend the Commerce Admin UI with custom columns, mass actions, order view buttons, or menu entries
- `commerce-app-storage` — back runtime actions with persistent, queryable DB storage
## References
- [assets/app.commerce.config.ts](assets/app.commerce.config.ts) — Minimal config template
© adobe · Apache-2.0 · adobe/skills