К основному содержанию
скилл CX Codex

commerce-app-migrate — скилл для Claude Code: как установить

Скилл commerce-app-migrate переносит проекты Adobe Commerce App Builder со Starter Kit на App Management. Запускается в корне репозитория.

Apache-2.0 256 установок ★ 335 обновлён 2026-11-14

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add adobe/skills --skill commerce-app-migrate -a claude-code
Открыть на GitHub

Что делает commerce-app-migrate

Скилл автоматизирует переход с Integration Starter Kit или Checkout Starter Kit на библиотеку @adobe/aio-commerce-lib-app. Перед запуском скрипт выполняет проверку файлов: в корневой папке обязательно должны присутствовать app.config.yaml, package.json и каталог actions/, src/ либо actions-src/.

Процесс включает анализ проекта, короткий опросник по конфигурации и сборку итогового файла app.commerce.config.ts. Флаг --auto отключает интерактивные подтверждения для CI, а режим --doc-scan-only находит устаревшие параметры в README.md и env.dist без изменения исходников. Конфигурацию mesh.json утилита не конвертирует — настройки API Mesh придётся переносить вручную.

Для запуска требуются Node.js версии 22+, установленный интерфейс aio CLI и пакет @adobe/aio-commerce-lib-app.

Какие задачи решает

  • перенести проект App Builder на архитектуру App Management
  • обновить точки расширения с Admin UI SDK v1 на v2
  • проверить устаревшие переменные в env.dist без правки кода
  • запустить миграцию проекта без диалоговых окон через флаг --auto

Примеры запросов агенту

  • Мигрируй этот проект App Builder на архитектуру App Management
  • Выполни миграцию проекта без подтверждений с флагом --auto
  • Проверь документацию и переменные окружения через --doc-scan-only

Как установить commerce-app-migrate

1Через Skills CLI (Vercel)

npx skills add adobe/skills --skill commerce-app-migrate -a claude-code

2Вручную: положить файлы

~/.claude/skills/commerce-app-migrate/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/commerce-app-migrate/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о commerce-app-migrate

Как установить commerce-app-migrate в Claude Code?

Выполните в терминале команду npx skills add adobe/skills --skill commerce-app-migrate -a claude-code.

Что делает commerce-app-migrate?

Скилл проверяет структуру проекта Adobe Commerce App Builder, анализирует интеграции и собирает единый конфигурационный файл app.commerce.config.ts.

Какие системные требования нужны для работы скилла?

В окружении должны быть установлены Node.js 22+, aio CLI и библиотека @adobe/aio-commerce-lib-app.

Исходный текст

SKILL.md · Apache-2.0
---
name: commerce-app-migrate
description: >
  Migrate an Adobe Commerce App Builder project from the Integration Starter Kit or Checkout Starter Kit to the new App Management approach. Run from the root of the App Builder project to be migrated. Pass --auto to skip confirmation prompts (suitable for CI or batch use) — auto mode prints a summary of all Q&A questions answered with their defaults. Pass --doc-scan-only to scan README.md and env.dist for outdated content without modifying any files. Env vars still read by runtime actions after migration are proposed as Business Configurations: accepted ones are added to businessConfig.schema and the action code is rewritten to read them with @adobe/aio-commerce-lib-config. Use when the user wants to migrate an App Builder project from the Integration Starter Kit or Checkout Starter Kit to the App Management approach, or mentions upgrading their Adobe Commerce extension architecture.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
  Run from the root of the App Builder project being migrated.
metadata:
  author: adobe
  sdk-package: "@adobe/aio-commerce-lib-app"
  version: "0.0.1"
---

# Migrate to App Management

Use this skill when the user wants to migrate an Adobe Commerce App Builder
project from the Integration Starter Kit or Checkout Starter Kit to the new
App Management approach using `@adobe/aio-commerce-lib-app`.

This skill orchestrates the full migration: detection → domain analysis → Q&A →
config assembly → execution. It leaves the project fully migrated and ready to deploy.

### Confirmation protocol

At each step marked **[await]**: end your turn immediately, output nothing further,
and wait for the developer's reply before proceeding.

**Autonomous mode:** If invoked with `--auto` or `--yes`, or the context indicates an
automated pipeline (no interactive terminal), skip all **[await]** points and proceed
directly to the next step.

**Doc-scan-only mode:** If invoked with `--doc-scan-only`, skip all migration steps after
the Analyzer. After Step 1 completes (Analyzer returns a `ProjectSnapshot`):

- If `alreadyMigrated === false`, output:

      --doc-scan-only requires the project to already be migrated to App Management.
      No app.commerce.config.ts (or .js) was found.

      Run /commerce-app-migrate (without --doc-scan-only) to perform the migration first.

  Then stop.

- If `alreadyMigrated === true`, apply any applicable Cross-cutting Warnings, then
  dispatch the Executor in doc-scan-only mode. No files are modified.
  Do not proceed to Steps 2–5.

---

## Preflight Check

Before doing anything else, verify the current directory looks like an App Builder project.
Check that ALL of these exist:

- `app.config.yaml`
- `package.json`
- At least one of: `actions/` directory OR `src/` directory OR `actions-src/` directory
  (some projects compile TypeScript from `actions-src/` to `actions/`; `actions/` may be
  gitignored and absent in a fresh checkout)

If none of those pass, stop immediately and output:

    This directory does not appear to be a Commerce App Builder project.
    Expected to find: app.config.yaml, package.json, and an actions/ or src/ directory.

    Please run this skill from the root of your App Builder project.

Do not proceed further if the preflight fails.

---

## Step 1: Run Analyzer Agent

Dispatch the Analyzer agent (defined in `${CLAUDE_SKILL_DIR}/agents/analyzer.md`) using the Agent tool.
The Analyzer reads the current directory and returns a `ProjectSnapshot` JSON object
(schema defined in `${CLAUDE_SKILL_DIR}/shared/schema.md`).

**Before printing the summary, check these early-exit conditions:**

**If `alreadyMigrated === true`:** Output:

    This project appears to already be migrated to App Management.
    Found: app.commerce.config.ts (or app.commerce.config.js with ESM defineConfig)

    Re-running migration would overwrite your existing configuration.
    If you want to re-generate specific sections, please specify which
    section to update: metadata / eventing / installation / adminUi / businessConfig

Then apply any applicable Cross-cutting Warnings (see subsection below).

Then dispatch the Executor agent (`${CLAUDE_SKILL_DIR}/agents/executor.md`) in
**doc-scan-only mode** to produce documentation recommendations for the project:

- Pass `mode = "doc-scan-only"` to the Executor
- Pass the `ProjectSnapshot` JSON from the Analyzer
- Pass `assembled config = null` (no new config to write)

The Executor will scan `README.md` and `env.dist` against the existing
`app.commerce.config.ts` and print the "Documentation recommendations" report
without modifying any files.

**Do not proceed to Steps 2–5 (domain agents, Q&A, config assembly, full execution)
unless the developer explicitly requests a specific section update.**

After the Executor prints the documentation recommendations, **stop**. Do not continue to
the "Detected project:" summary block or the migration confirmation prompt below.

After the Analyzer returns, print a human-readable summary:

    Detected project:
      Type:             <starterKitType> Starter Kit
      Auth mode:        <authMode> (<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "Both PaaS + SaaS" | unknown = "Unknown">)
      Action packages:  <comma-separated list of package names> (<count> packages)
      Onboarding:       <comma-separated list of script paths with purposes, or "none">
      Package manager:  <packageManager>

    Migration will include: <list domains where confidence !== "none">

Apply any applicable Cross-cutting Warnings (see subsection below).

**If `hasMeshConfig === true`**, also append:

    ⚠ API Mesh configuration detected (mesh.json).
    Mesh configuration cannot be migrated automatically and must be preserved manually.

Then ask:

    Does this look correct? (yes / no — if no, describe what's wrong)
    Press Enter or type "yes" to proceed automatically.

**[await]**

**Handle corrections:**

- If developer corrects `starterKitType`, update it in the ProjectSnapshot before proceeding
- If developer corrects `authMode`, update it
- Re-print summary with corrections and ask again until confirmed

**Handle unknown starterKitType:**
If `starterKitType === "unknown"`, check `extensionPointsInUse`:

- If `"commerce/backend-ui/1"` is present → this is an **Admin UI SDK v1 extension**. Proceed
  with `starterKitType = "unknown"` — the admin-ui-sdk domain agent will migrate it to v2.
  Print a note: "Detected Admin UI SDK v1 (commerce/backend-ui/1). Migrating to v2 (commerce/backend-ui/2)."
- If all confidence values are `"none"` AND `extensionPointsInUse` is empty:
  Output:

      This project does not appear to be based on the Integration Starter Kit
      or Checkout Starter Kit. No event consumers, webhooks, or Admin UI SDK
      patterns were detected.

      Migration can still generate a minimal app.commerce.config.ts with metadata
      only. Continue? (yes / no)

  If developer says no, stop. If yes, proceed with empty domain results.

- Otherwise, ask the developer:

      I couldn't determine which starter kit this project is based on.
      Is this an Integration Starter Kit or a Checkout Starter Kit?
      Options: [integration / checkout / adminUiSdk / custom]

      Not sure? See the documentation:
        • Integration Starter Kit: https://developer.adobe.com/commerce/extensibility/starter-kit/integration/
        • Checkout Starter Kit:     https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/

  Update the ProjectSnapshot with their answer before proceeding.

### Cross-cutting Warnings

Apply these whenever the corresponding field is set in the ProjectSnapshot, regardless
of migration state. Append each matching block to whatever output is currently being built.

**If `openWhiskTriggers` is non-empty**, append:

    ⚠ OpenWhisk triggers detected (cannot be auto-migrated):
      <list each trigger description>
    These scheduled triggers have no direct equivalent in App Management.

Read `${CLAUDE_SKILL_DIR}/shared/migration-warnings.md` (OpenWhisk Triggers section)
and present the replacement options to the developer.

**If `hasApiGateway === true`**, append:

    ⚠ OpenWhisk API Gateway routes detected (apis: blocks in runtime manifest).
    These HTTP routes have no direct equivalent in App Management.

Read `${CLAUDE_SKILL_DIR}/shared/migration-warnings.md` (API Gateway section)
and present the migration options to the developer.

**If `hasSequences === true`**, append:

    ⚠ OpenWhisk sequences detected.
    Action sequences have no equivalent in App Management.

Read `${CLAUDE_SKILL_DIR}/shared/migration-warnings.md` (Sequences section)
and present the refactoring guidance to the developer.

---

## Step 2: Dispatch Domain Agents in Parallel

For each domain where `confidence !== "none"`, dispatch the corresponding agent
**at the same time** using the Agent tool (all in one parallel call):

| confidence field                                                     | Agent file                                      |
| -------------------------------------------------------------------- | ----------------------------------------------- |
| `confidence.events !== "none"`                                       | `${CLAUDE_SKILL_DIR}/agents/events.md`          |
| `confidence.webhooks !== "none"`                                     | `${CLAUDE_SKILL_DIR}/agents/webhooks.md`        |
| `confidence.adminUiSdk !== "none"`                                   | `${CLAUDE_SKILL_DIR}/agents/admin-ui-sdk.md`    |
| `confidence.businessConfig !== "none"` or `envDistKeys` is non-empty | `${CLAUDE_SKILL_DIR}/agents/business-config.md` |

Each agent receives:

- The `ProjectSnapshot` JSON
- Instruction to read the relevant files in the current directory using their own Read tools

Collect all returned `DomainResult` objects. Each has `domain`, `configFragment`,
and `unresolvedQuestions` fields (schema in `${CLAUDE_SKILL_DIR}/shared/schema.md`).
The business-config result may also carry `envMigrations`: environment variables still read
by runtime actions that were added to `businessConfig.schema` as candidates (fields tagged
`"_source": "env"`).

---

## Step 3: Grouped Q&A

Collect all `unresolvedQuestions` from every `DomainResult`.
If there are no unresolved questions across all domains, skip to Step 4.

Present all questions in a single grouped session (format defined in `${CLAUDE_SKILL_DIR}/shared/questions.md`):

- Group by domain
- For questions with `default` values, show as confirmations: "(suggested: X)"
- Number questions sequentially across domains

**[await]**

For each answer received:

- Apply it to the `configFragment` of the corresponding `DomainResult`
- Use the question `id` to locate the exact field to update

If the developer accepts a suggested value (presses Enter / says "yes"), use the `default`.

**Special case — skip-by-default questions** (where `default` is `"no"`):
These questions ask whether to include an optional section that was omitted from the
`configFragment` because required data was missing (e.g. a provider direction with no
deployed action package). Interpret the developer's reply as:

- `"no"` (or pressing Enter) → leave the section out of the `configFragment`; do nothing
- `"yes"` or any action string → add the section back; prompt for the runtime action name
  if not already specified in the reply, then apply it to the `configFragment`

**Env var questions (`businessConfig.env.<KEY>.migrate`):**
Group these under an "Environment variables" heading within the business-config domain. For each answer:

- `"yes"` (default) → keep the field in `businessConfig.schema`
- `"no"` → remove the field tagged for that key from `businessConfig.schema` and drop its
  `envMigrations` entry; the variable stays a manual environment variable

If removal leaves `businessConfig.schema` empty, omit `businessConfig` from the config.
The remaining `envMigrations` entries are the selected migrations passed to the Executor in Step 5.

**Autonomous mode — auto-accepted defaults summary:**

In `--auto` mode, after applying all question defaults, print:

    ── Auto-accepted defaults ────────────────────────────────────────
      The following questions were answered automatically (--auto mode):
      [  <domain> : <question id> = "<default value>"  ]
         ← one line per question that had an explicit default; omit entire section if no questions existed →

Omit this section entirely if there were no unresolved questions across all domains.

---

## Step 4: Assemble app.commerce.config.ts

Read `package.json` from the current directory to extract metadata.

Assemble the full config content by merging all `configFragment` objects:

```typescript
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "<derived from package.json name>",
    displayName: "<derived from package.json name>",
    version: "<from package.json version or 1.0.0>",
    description:
      "<from package.json description or 'Commerce App Builder application'>",
    upgradeMode: "auto",
  },
  // eventing: { ... }          ← from events DomainResult, if present
  // installation: { ... }      ← from webhooks DomainResult, if present
  // adminUi: { ... }           ← from admin-ui-sdk DomainResult (migrated from v1), if present
  // businessConfig: { ... }    ← from business-config DomainResult, if present
});
```

**Metadata derivation rules:**

- `id`: Check `extension-manifest.json` first — if it has an `id` field and it is not
  the same as the package name boilerplate, use it (apply same normalization: lowercase,
  replace non-alphanumeric with `-`, trim, max 50 chars).
  Otherwise take `name` from `package.json`. Strip npm scope (`@scope/`). Replace
  any non-alphanumeric characters (except `-`) with `-`. Lowercase the entire string.
  Trim leading/trailing dashes. Max 50 chars.
  Known ISK boilerplate names to skip in favor of extension-manifest.json:
  `commerce-integration-starter-kit`, `starter-kit`, `commerce-checkout-starter-kit`,
  `aio-app-builder-template`.
- `displayName`: Check `extension-manifest.json` first — if it has a `displayName` field,
  use it (truncated to 50 chars). Otherwise title-case the `id` (replace `-` with spaces).
  Max 50 chars.
- `version`: Use `package.json` `version`. Default: `"1.0.0"`.
- `upgradeMode`: Use `"manual"` (currently the default while upgrade execution
  stabilizes) unless the developer explicitly asks for automatic execution. `"auto"` is
  experimental: the generated post-deploy hook plans an upgrade, starts it and shows
  its progress until it finishes. In `"manual"` mode, the hook leaves the plan pending
  without starting execution.
- `description`: Use `package.json` `description` if present.
  If the description exceeds 255 characters, do NOT truncate it mid-sentence.
  Instead, rewrite it: read the full description and compose a shorter one that
  fits in 255 characters while preserving the essential meaning — what the app
  does, which systems it connects, and its key capabilities. Prefer complete
  sentences; drop secondary detail (deployment notes, exhaustive feature lists)
  before core purpose. Never end with `"..."` — the rewritten description must
  read as intentional, not cut off.
  The rewritten value applies only to the config: the Executor records the original
  `package.json` description before init and restores it afterwards (init writes the
  config value back into `package.json`).
  If absent or empty, check `extension-manifest.json` `description` field (apply the
  same rewrite rule).
  If neither has a description: `"Commerce App Builder application"`.

**productDependencies comment:**
If `ProjectSnapshot.productDependencies` is non-null (has `minVersion` and/or `maxVersion`):
Insert this comment block in the assembled TypeScript, immediately AFTER the copyright header
and BEFORE the `import { defineConfig }` line:

```typescript
// Product version constraints (no App Management equivalent — for reference only):
// Adobe Commerce compatibility: >= <minVersion>, < <maxVersion>
// Contact Adobe Commerce Marketplace for guidance on version enforcement.
```

Omit the `< <maxVersion>` part if `maxVersion` is null. Omit the `>= <minVersion>` part if
`minVersion` is null. If both are null or `productDependencies` is null, omit the comment entirely.

Print the assembled TypeScript content to the terminal:

    Here is the app.commerce.config.ts that will be created:

    ─────────────────────────────────────────────────────────
    import { defineConfig } from '@adobe/aio-commerce-lib-app/config'

    export default defineConfig({
      ...assembled content...
    })
    ─────────────────────────────────────────────────────────

    Does this look correct? (yes / no — if no, which section needs updating?)
    Press Enter or type "yes" to proceed automatically.

**[await]**

**Handle rejection:**
If the developer says no, ask: "Which section needs updating? (metadata / eventing /
installation / adminUi / businessConfig)"

Then ask the specific corrective question for that section, update the assembled
config accordingly, re-print, and ask for confirmation again.

Repeat until the developer confirms. Do NOT restart the entire flow — only
re-enter the Q&A for the specific section being corrected.

---

## Step 5: Execute Migration

Dispatch the Executor agent (`${CLAUDE_SKILL_DIR}/agents/executor.md`) with:

1. The assembled `app.commerce.config.ts` TypeScript content as a string
2. The final `ProjectSnapshot` JSON
3. The remaining `envMigrations` from Step 3 (empty array if none)

The Executor performs all file writes and CLI commands and prints the migration summary.

If the Executor reports an error, relay the error message and the step that failed.
Do not attempt to roll back changes — the git branch created by the Executor provides
a rollback point (`git checkout main` to abandon the migration).

---

## Notes

- Domain agents (Step 2) run **in parallel** — dispatch all eligible agents in one Agent tool call
- Analyzer (Step 1) and Executor (Step 5) are sequential — Analyzer first, Executor last
- This skill runs in the **developer's project directory**, not the migration skill repository
- **Documentation recommendations** are produced by the Executor and cover:
  - README.md sections flagged by 5 patterns: ISK onboarding commands, old env var references, outdated architecture diagrams, credential-family semantic matching (IMS/SaaS, PaaS/OAuth1, workspace), and env setup boilerplate (`cp env.dist .env`)
  - env.dist entries grouped into three buckets: safe-to-remove (managed by App Management), review-manually (referenced in action source files, grouped by file), and onboarding-only (used only in onboarding scripts)
  - Rule 9 catches unreferenced env.dist variables not matched by any other rule and flags them for manual review
  - Category C (README) requires ≥ 5 flagged sections to emit the recommendations block
- **Env vars to Business Configurations**: the business-config agent proposes env vars that runtime actions still read (excluding auth, workspace, event, webhook and platform keys) as `businessConfig.schema` fields (secrets as `password`). For accepted ones, the Executor rewrites the action code from `params.<KEY>` to `@adobe/aio-commerce-lib-config` reads. In `--auto` mode all candidates are accepted
- **`--auto` mode** prints a summary of all Q&A questions answered automatically with their defaults (omitted if no questions existed)
- **`productDependencies`** version constraints from `extension-manifest.json` are auto-inserted as a comment block immediately before the `import { defineConfig }` line in the generated `app.commerce.config.ts`
- **Internal metadata fields** (`_directionWarning`, `_source`) may be added by domain agents to `configFragment` objects — the Executor strips these before writing files so they never appear in the output TypeScript

## Supporting Files

Agent files dispatched by this skill:

- [Analyzer](agents/analyzer.md)
- [Events](agents/events.md)
- [Webhooks](agents/webhooks.md)
- [Admin UI SDK](agents/admin-ui-sdk.md)
- [Business Config](agents/business-config.md)
- [Executor](agents/executor.md)

Shared reference files:

- [Schema](shared/schema.md)
- [Questions format](shared/questions.md)
- [Migration warnings](shared/migration-warnings.md)
- [External references](shared/references.md)

© adobe · Apache-2.0 · adobe/skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
adobe-commerce membrane Интегрирует агента с Adobe Commerce через Membrane CLI для управления заказами, товарами, счетами и автоматизации интернет-магазина. CX Codex +1 167установок migrate-app-to-flows cognitedata Скилл migrate-app-to-flows автоматизирует перенос веб-приложений с устаревшей платформы Dune на инфраструктуру Flows (appsApi). Он проверяет конфигурации и настраивает сетевые политики. CX Codex +1 1 700установок migrate-ai-sdk-v6-to-v7 vercel Скилл migrate-ai-sdk-v6-to-v7 переводит проекты с Vercel AI SDK 6.x на версию 7.0. Помогает обновить зависимости, исправить сломанные типы и заменить устаревшие параметры вызовов. CX Codex +1 6 000установок tsdown-migrate rolldown Скилл tsdown-migrate ведёт миграцию TypeScript-библиотеки с tsup на tsdown: таблицы соответствия опций, различия в значениях по умолчанию и замена убранных опций. CX Codex +1 408установок nemo-relay-migrate-from-flow NVIDIA Corporation and Affiliates Скилл nemo-relay-migrate-from-flow для механической миграции кода, документации и конфигов с NeMo Flow на NeMo Relay. Работает с Python, Rust, Node.js, Go, C FFI, CLI и параметрами наблюдаемости. CX Codex +1 171установок migrate-to-parallel parallel-web Скилл migrate-to-parallel для Claude Code, Codex, Cursor и других IDE переносит интеграции с Exa, Tavily, Perplexity или Firecrawl на продукты Parallel, сохраняя поведение приложения. CX Codex +1 3 800установок

Из того же набора108

Весь набор →
cdp-ext-pilot Скилл cdp-ext-pilot запускает Chromium с распакованным расширением, открывает его боковую панель, попап или настройки и управляет через CDP. Для тестирования и автоматизации UI расширений. CX Codex +1 282установок page-reduce Скилл page-reduce для Claude Code превращает веб-страницу в структурный каркас с токенами для текста, изображений и действий. Каркас используют при подготовке миграции в AEM Edge Delivery Services и анализе блоков. CX Codex +1 281установок domain-mask Скилл domain-mask показывает реальный URL под чистым доменом через локальный HTTPS-прокси с доверенным сертификатом. Для демо, записей скринкастов и скриншотов. CX Codex +1 281установок page-prep Скилл page-prep находит и скрывает баннеры куки, пейволлы и модальные окна перед парсингом или созданием скриншотов с помощью Playwright CLI. CX Codex +1 281установок qa Скилл qa проводит автоматический аудит сайта на AEM Edge Delivery Services после деплоя. Он находит визуальные и структурные регрессии, но никогда сам не меняет код. CX Codex +1 253установок run-workflow Скилл, который маршрутизирует запросы к MCP-серверу run-workflow. Через него агент собирает, запускает, публикует и сохраняет Adobe Firefly-воркфлоу. CX Codex +1 250установок appbuilder-workfront Скилл appbuilder-workfront для Claude Code направляет этапы создания UI-расширения Workfront на Adobe App Builder к скиллам по фронтенду, серверным функциям и тестированию. CX Codex +1 245установок wf-planning-solution-architect Скилл wf-planning-solution-architect для проектирования и отладки рабочих пространств Adobe Workfront Planning: иерархии типов записей, формулы, лимиты API и выбор уровня тарифа. CX Codex +1 223установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой