commerce-app-business-config — скилл для Claude Code
Скилл commerce-app-business-config добавляет типизированные поля бизнес-конфигурации в приложение Adobe Commerce через businessConfig.schema. Мерчант настраивает их в Commerce Admin, приложение читает значения в рантайме.
Apache-2.0 334 установок ★ 335 обновлён 2026-11-07
npx skills add adobe/skills --skill commerce-app-business-config -a claude-codeЧто делает commerce-app-business-config
Скилл правит массив businessConfig.schema в существующем app.commerce.config.ts. Каждая запись описывает одно поле, которое Commerce Admin отрисует как UI-элемент: текст, пароль, email, url, телефон, булевый переключатель или список с одним/несколькими вариантами.
Перед правкой скилл проверяет, что проект реально инициализирован: есть app.commerce.config.ts, сгенерирован src/commerce-extensibility-1/ и установлен @adobe/aio-commerce-lib-app. Если конфига нет, он останавливается и зовёт commerce-app-init. Если конфиг есть, но проект не инициализирован, запускает npx @adobe/aio-commerce-lib-app init.
Валидация типов идёт до записи. Для single-списков дефолт обязателен и должен совпадать с одним из option value. Для password дефолт всегда "", непустое значение отклоняется, чтобы секреты не попадали в конфиг. Пустой businessConfig.schema не пройдёт сборку — минимум одно поле.
Затем скилл регистрирует extension point commerce/configuration/1 в app.config.yaml и install.yaml, ставит зависимость @adobe/aio-commerce-lib-config и запускает aio app build для проверки. Требуется Node.js 22+, aio CLI и @adobe/aio-commerce-lib-app.
Какие задачи решает
- добавить мерчант-настраиваемое поле в Commerce Admin
- задать тип поля: text, password, email, url, tel, boolean или list
- провалидировать дефолтные значения до сборки
- зарегистрировать extension point
commerce/configuration/1 - проверить конфиг сборкой
aio app build
Примеры запросов агенту
- Добавь поле API-ключа с типом password в бизнес-конфигурацию приложения
- Сделай single-select список регионов с дефолтом eu и вариантами EU/US
- Добавь булевый флаг debug_mode с дефолтом false
Как установить commerce-app-business-config
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-business-config -a claude-code2Вручную: положить файлы
~/.claude/skills/commerce-app-business-config/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/commerce-app-business-config/
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-business-config -a codex2Вручную: положить файлы
.agents/skills/commerce-app-business-config/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-business-config -a cursor2Вручную: положить файлы
.cursor/skills/commerce-app-business-config/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install adobe/skills plugins/commerce/app-management/skills/commerce-app-business-config2Вручную: положить файлы
.github/skills/commerce-app-business-config/SKILL.md1Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-business-config -a gemini-cli2Командой платформы
gemini skills install https://github.com/adobe/skills --path plugins/commerce/app-management/skills/commerce-app-business-configВручную: положить файлы
.devin/skills/commerce-app-business-config/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add adobe/skills --skill commerce-app-business-config -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о commerce-app-business-config
Как установить commerce-app-business-config в Claude Code?
Выполни npx skills add adobe/skills --skill commerce-app-business-config -a claude-code, затем скилл появится в ~/.claude/skills/commerce-app-business-config/SKILL.md.
Что делает commerce-app-business-config?
Добавляет и меняет поля в businessConfig.schema внутри app.commerce.config.ts. Каждое поле становится настройкой в Commerce Admin, а приложение читает её через @adobe/aio-commerce-lib-config.
Что нужно для работы скилла?
Node.js 22+, aio CLI и инициализированное приложение с @adobe/aio-commerce-lib-app. Если app.commerce.config.ts отсутствует, сначала запускается commerce-app-init.
Исходный текст
SKILL.md · Apache-2.0
---
name: commerce-app-business-config
description: >
Manage custom business configuration in an Adobe Commerce app. Use when the
user wants to add, modify, or remove merchant-configurable settings (config
fields, admin config, store configuration) exposed through Commerce Admin.
Creates typed config fields (text, password, email, url, tel, boolean, list)
in businessConfig.schema. Requires a base app initialized with commerce-app-init.
license: Apache-2.0
compatibility: >
Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app installed.
Requires a base app initialized with commerce-app-init.
metadata:
author: adobe
---
# Configure Commerce App Business Config
Adds or modifies the `businessConfig.schema` array in an existing `app.commerce.config.ts`.
Each entry in the schema defines one merchant-configurable setting that Commerce Admin will render as a UI field.
Other extensibility domains (webhooks, events) are added separately via their own skills.
## Prerequisites
- Verify the app is **scaffolded and initialized**, not merely that the config exists. Require **both**:
- `app.commerce.config.ts` present in the project root, **and**
- the project initialized — signalled by the generated `src/commerce-extensibility-1/` directory and installed `node_modules` (the `@adobe/aio-commerce-lib-app` dependency).
- If `app.commerce.config.ts` is **missing**, stop and invoke `commerce-app-init` first (it writes the config, then runs init).
- If the config is **present but the project is not initialized** (no `src/commerce-extensibility-1/` or `node_modules`), run `npx @adobe/aio-commerce-lib-app init` before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
## Step 1 — Understand intent
For each setting the user wants to expose, gather:
- **Name** — machine identifier for the field (used as the config key read by the app at runtime)
- **Type** — one of: `list`, `text`, `password`, `email`, `url`, `tel`, `boolean`
- **Label** (optional) — human-readable label shown in Admin
- **Description** (optional) — help text shown alongside the field in Admin
- **Default value** (optional, type-dependent — see constraints in Step 2)
- For `list` fields additionally: **`selectionMode`** (`"single"` or `"multiple"`) and **`options`** (each with a `label` and `value` string)
## Step 2 — Derive config values
Apply the following per-type validation rules before writing. Surface any issues to the user before proceeding.
| Field | Constraint |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `name` | Required, non-empty string |
| `type` | Required; one of `list`, `text`, `password`, `email`, `url`, `tel`, `boolean` |
| `label` | Optional string |
| `description` | Optional string |
| `list.selectionMode` | Required for list fields: `"single"` or `"multiple"` |
| `list.options` | Required for list fields; each option needs both `label` and `value` strings |
| `list/single` default | Required; must match one of the option `value` strings (non-empty) |
| `list/multiple` default | Optional array of strings (defaults to `[]`); each element must match an option value |
| `text` default | Optional string (defaults to `""`) |
| `password` default | Must be `""` — any non-empty default is rejected to prevent secrets in config |
| `email` default | Optional; `""` or a fully valid email address |
| `url` default | Optional; `""` or a fully valid absolute URL |
| `tel` default | Optional; `""` or matches `/^\+?[0-9\s\-()]+$/` (digits, spaces, hyphens, parens, optional `+`) |
| `boolean` default | Optional boolean (defaults to `false`) |
`businessConfig.schema` must contain at least one field — an empty array is rejected at build time.
## Step 3 — Update `app.commerce.config.ts`
Add (or merge into) the top-level `businessConfig.schema` array, preserving all other domains. If the config already has a `businessConfig` key, append to `businessConfig.schema` rather than replacing it.
Minimal examples:
```ts
businessConfig: {
schema: [
// Password (masked input — API keys, secrets)
{ name: "api_key", type: "password", label: "API Key", default: "" },
// Single-select list
{
name: "region", type: "list", selectionMode: "single",
label: "Region",
options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
default: "eu", // required; must match an option value
},
// Boolean toggle
{ name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },
// Dynamic list — options resolved at runtime via a factory that receives the action's params.
// Required `default` factory for single-select; optional for multiple (falls back to []).
{
name: "paymentMethod", type: "dynamicList", selectionMode: "single",
label: "Default Payment Method",
options: async (params) => {
const methods = await fetchPaymentMethods(params.SOME_API_KEY);
return methods.map((m) => ({ label: m.title, value: m.code }));
},
default: (resolvedOptions) => resolvedOptions[0].value,
},
],
}
```
See [assets/business-config.ts](assets/business-config.ts) for the full reference showing all field types.
## Step 4 — Register the extension point
Run init so that `commerce/configuration/1` is added to `app.config.yaml` and `install.yaml`, and the required `@adobe/aio-commerce-lib-config` dependency is installed. This is idempotent — safe to run even if the extension is already registered.
```sh
npx @adobe/aio-commerce-lib-app init
```
## Step 5 — Validate
Build the project to confirm the updated config is valid:
```sh
aio app build
```
A build failure with a validation error points directly to the offending field.
## Reading config in runtime actions
Use `@adobe/aio-commerce-lib-config` to read the values merchants set in Commerce Admin.
The library must be initialized with the generated schema on every action invocation before any config call.
### Basic pattern
```typescript
import {
initialize,
getConfigurationByKey,
getConfiguration,
byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };
export async function main(params) {
await initialize({ schema });
// Required to decrypt `password` fields — see "Password fields" below
const options = { encryptionKey: params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY };
// Read a single field — config is null if the key has never been set
const { config } = await getConfigurationByKey(
"api_key", // the `name` from your schema
byCodeAndLevel("global", "global"), // scope
options,
);
const apiKey = config?.value ?? "";
// Read all fields for a scope
const { config: allConfig } = await getConfiguration(
byCodeAndLevel("global", "global"),
options,
);
// allConfig is an array of { name, value, origin } entries
return { statusCode: 200, body: { success: true } };
}
```
### Scope selectors
| Selector | When to use |
| ----------------------------------------- | -------------------------------------------------- |
| `byCodeAndLevel("global", "global")` | App-wide settings — applies to all stores |
| `byCodeAndLevel(storeCode, "store_view")` | Per store view (most specific) |
| `byCode(storeCode)` | Resolves using the default level for the scope |
| `byScopeId(scopeId)` | When you have the scope's numeric ID from Commerce |
Values inherit from parent scopes — a field not set on `store_view` falls back to `store`, `website`, then `global`.
### Password fields
`aio app build` generates `AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` automatically into `.env` the first time it encounters a password field (and validates it on subsequent builds). No manual setup needed.
The library does not read the key from the environment. Pass it as the `encryptionKey` option on every `getConfigurationByKey`, `getConfiguration`, and `setConfiguration` call, as in the example above. A call that reads or writes a non-empty `password` value without it throws `Encryption key has not been given`.
The key reaches `params` only if the action declares it as an input. Add it to the `inputs` of **every** action that makes these calls in `ext.config.yaml` — declaring it on one action does not make it available to the others:
```yaml
inputs:
AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY
```
With the option and the input in place, password values are returned as plaintext.
## Common Issues
- **`list/single` default missing**: Single-select list fields require a `default` — it can't be omitted. It must exactly match one of the option `value` strings.
- **`Encryption key has not been given`**: A config call touched a stored `password` value without the `encryptionKey` option, or the action does not declare the `AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` input, so `params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY` is `undefined`.
- **`defineConfig` not found**: Ensure `@adobe/aio-commerce-lib-app` is installed and `defineConfig` is imported from `@adobe/aio-commerce-lib-app/config`.
## Quality Bar
- `aio app build` completes without errors
## Chaining
After `aio app build` passes:
- **Add webhook interceptors** — invoke `commerce-app-webhooks` to intercept Commerce operations before or after they execute
- **Add event subscriptions** — invoke `commerce-app-eventing` to subscribe to Commerce or external events
- **Extend the Admin UI** — invoke `commerce-app-admin-ui` to add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin
## References
- [assets/business-config.ts](assets/business-config.ts) — Reference config showing all field types with inline constraint comments
© adobe · Apache-2.0 · adobe/skills