adobe · obarcelonap · Jul 10, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jul 2, 2026
diff --git a/.changeset/commerce-plugin-bootstrap.md b/.changeset/commerce-plugin-bootstrap.md
@@ -0,0 +1,6 @@
+---
+"@adobe/aio-commerce-plugin-app-management": minor
+"@adobe/aio-commerce-plugin-app-migration": minor
+---
+
+Promote Commerce plugins through the stable skills release process.
diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md
@@ -496,6 +496,17 @@ When ready to publish to npm, use the **Promote to Release** workflow dispatch (
 
 If there were snapshot versions like `1.2.5-beta-20260313T120000` on Artifactory, the resulting stable release is `1.2.5`.
 
+Commerce plugins under `plugins/commerce/*` use the same changeset flow, but they are private
+workspace packages and are not published to npm. A changeset targeting a plugin package is the
+release intent for the stable skills channel. When the Release PR bumps a plugin version, the
+public release workflow opens or updates a promotion PR in
+[`adobe/skills`](https://github.com/adobe/skills) from the fixed branch
+`promote/adobe-aio-commerce-sdk`.
+
+Skill-only Release PRs are valid. They do not publish npm packages and do not send the package
+Slack notification, but they still run the `adobe/skills` promotion step and back-sync the
+plugin version/changelog updates to `main`.
+
 #### Back-sync
 
 After a public release, the back-sync is automatic — the workflow merges `release` directly into `main` via a merge commit. No manual step needed.
@@ -516,3 +527,12 @@ If the deploy key ever needs to be rotated:
 2. Add the public key under **Settings → Deploy keys** (enable write access) and note the new key ID.
 3. Update the `DEPLOY_KEY` Actions secret with the new private key.
 4. Update the ruleset bypass actor with the new key ID via `gh api`.
+
+The Commerce plugin promotion step also requires an `ADOBE_SKILLS_TOKEN` Actions secret. Provision
+it as a fine-grained GitHub personal access token with the following settings:
+
+- **Resource owner:** `adobe`
+- **Repository access:** `adobe/skills` only
+- **Permissions:** Metadata (read), Contents (read/write), Pull requests (read/write)
+- **Expiration:** 366 days (the maximum); set a calendar reminder to regenerate it before it
+  expires, then update the `ADOBE_SKILLS_TOKEN` Actions secret with the new value.
diff --git a/.github/workflows/publish-public.yml b/.github/workflows/publish-public.yml
@@ -16,13 +16,16 @@ jobs:
     outputs:
       published: ${{ steps.changesets.outputs.published }}
       publishedPackages: ${{ steps.changesets.outputs.publishedPackages }}
+      promotedSkills: ${{ steps.promote-skills.outputs.promotedSkills }}
     permissions:
       contents: write
       pull-requests: write
       packages: write
       id-token: write
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 2
 
       - uses: ./.github/actions/setup-release
         with:
@@ -53,10 +56,48 @@ jobs:
           release-channel: public
           slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
 
+      # hasChangesets is false only on the run that lands right after the "Version
+      # Packages" PR merges, which is the one commit where diffing against HEAD^1
+      # reflects the actual version bump. `published` can't gate this instead:
+      # skill-only releases never publish to npm, so `published` stays false even
+      # when a plugin version legitimately changed.
+      - name: Detect changed Commerce plugin versions
+        id: changed-plugins
+        if: steps.changesets.outputs.hasChangesets == 'false'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          SOURCE_REPOSITORY_PATH: ${{ github.workspace }}
+        with:
+          script: |
+            const { detectChangedCommercePluginVersions } = await import('${{ github.workspace }}/scripts/source/ci/release/promote-skills.ts');
+            await detectChangedCommercePluginVersions(core, exec, process.env.SOURCE_REPOSITORY_PATH);
+
+      - name: Checkout adobe/skills
+        if: steps.changed-plugins.outputs.changed == 'true'
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: adobe/skills
+          path: adobe-skills
+          token: ${{ secrets.ADOBE_SKILLS_TOKEN }}
+          fetch-depth: 0
+
+      - name: Promote changed Commerce plugins to adobe/skills
+        id: promote-skills
+        if: steps.changed-plugins.outputs.changed == 'true'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          SOURCE_REPOSITORY_PATH: ${{ github.workspace }}
+          SKILLS_REPOSITORY_PATH: ${{ github.workspace }}/adobe-skills
+        with:
+          github-token: ${{ secrets.ADOBE_SKILLS_TOKEN }}
+          script: |
+            const { default: execPromoteSkills } = await import('${{ github.workspace }}/scripts/source/ci/release/promote-skills.ts');
+            await execPromoteSkills(core, exec, github, context);
+
   back-sync:
     name: Back-sync to main
     needs: release
-    if: needs.release.outputs.published == 'true'
+    if: needs.release.outputs.published == 'true' || needs.release.outputs.promotedSkills == 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: write

diff --git a/plugins/commerce/AGENTS.md b/plugins/commerce/AGENTS.md
@@ -2,33 +2,62 @@
 
 Rules for modifying skills in `plugins/commerce/`. Follow these whenever you add, edit, or review a skill.
 
-## Skill frontmatter
+## Plugin releases
 
-Every skill SKILL.md must include `metadata.version`. Increment it whenever the skill changes meaningfully (wording, logic, chaining, examples):
+Each plugin is a private pnpm workspace package. Use changesets to express release intent:
 
-```yaml
-metadata:
-  author: adobe
-  sdk-package: "@adobe/aio-commerce-lib-app"
-  version: "0.0.1" # increment when the skill changes meaningfully
-```
+1. Run `pnpm changeset add`.
+2. Select the plugin package, for example `@adobe/aio-commerce-plugin-app-management`.
+3. Choose the semver bump for the plugin change.
+4. Write a concise, user-facing changeset message.
 
-## Plugin version files
+Do not manually bump versions in `.tessl-plugin/plugin.json` or `.claude-plugin/plugin.json`. The
+plugin `package.json` is the authoritative version source; release automation syncs that version
+into the plugin manifests.
 
-`tile.json` and `.claude-plugin/plugin.json` at the plugin root carry the same `version` and `summary`. Bump both in lockstep whenever skills in the plugin change:
+Plugin semver rules:
+
+- `patch` — wording, examples, or minor clarifications with no behavioral change.
+- `minor` — new skills, new references or assets, or additive behavioral changes.
+- `major` — removed skills, renamed skills that break installs, or behavioral changes that break existing usage patterns.
+
+When adding a new skill to a plugin, also add its directory to `.tessl-plugin/plugin.json`'s
+`skills` array:
 
 ```json
-{ "version": "1.1.1" }
+"skills": ["skills/commerce-app-<name>"]
 ```
 
-When adding a new skill to a plugin, also add a matching entry to `tile.json`:
+## Plugin README files
 
-```json
-"skills": {
-  "commerce-app-<name>": {
-    "path": "skills/commerce-app-<name>/SKILL.md"
-  }
-}
+Plugin `README.md` files are copied verbatim to `adobe/skills` and must be stable-channel-ready:
+
+- Installation commands reference `adobe/skills`, not `adobe/aio-commerce-sdk`.
+- Do not add experimental banners.
+- Do not include contributor-only sections such as local testing, quality review, or eval workflows. Put contributor guidance in this file or `plugins/commerce/README.md`.
+
+## Skill frontmatter
+
+Each `SKILL.md` must open with a YAML frontmatter block. Required fields:
+
+- `name` — kebab-case identifier; must match the skill's directory name as referenced in `.tessl-plugin/plugin.json`'s `skills` array
+- `description` — multi-line routing description (use `>` block scalar); written to tell the agent _when_ to invoke the skill, not to describe its contents
+- `license` — always `Apache-2.0`
+- `compatibility` — runtime and package requirements (use `>` block scalar)
+- `metadata.author` — always `adobe`
+
+```yaml
+---
+name: commerce-app-example
+description: >
+  One or two sentences that tell the agent when to use this skill.
+license: Apache-2.0
+compatibility: >
+  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
+  Requires a base app initialized with commerce-app-init.
+metadata:
+  author: adobe
+---
 ```
 
 ## Inline examples are required

diff --git a/plugins/commerce/README.md b/plugins/commerce/README.md
@@ -18,8 +18,28 @@ Skills are available through two channels with different stability guarantees:
 | **Latest** | This repo (`adobe/aio-commerce-sdk`)              | Experimental — may change at any time | Contributors, early adopters, unreleased features |
 | **Stable** | [`adobe/skills`](https://github.com/adobe/skills) | Production-ready, tested releases     | Everyone else                                     |
 
-For most developers, install from `adobe/skills`. The commands in each plugin's README install from this repository and are intended for contributors and early adopters.
+For most developers, install from `adobe/skills`. The commands in each plugin's README target the stable channel.
 
 ## Contributing
 
 See [AGENTS.md](./AGENTS.md) for authoring guidelines.
+
+### Local testing
+
+Install skills directly from a local checkout into a target project:
+
+```sh
+cd ~/my-commerce-app
+pnpx skills add /path/to/aio-commerce-sdk/plugins/commerce/app-management --yes
+pnpx skills add /path/to/aio-commerce-sdk/plugins/commerce/app-migration --yes
+```
+
+### Quality review and evals
+
+Before shipping a skill, run the Tessl reviewer from the plugin directory:
+
+```sh
+pnpx tessl skill review skills/<skill-name>
+```
+
+Implemented skills may include evals in `skills/<skill-name>/evals/evals.json`. Eval results are excluded from version control; only `evals/evals.json` is committed.
diff --git a/plugins/commerce/app-management/README.md b/plugins/commerce/app-management/README.md
@@ -1,7 +1,5 @@
 # Commerce App Management Skills
 
-> ⚠️ **Experimental** — These skills are under active development and subject to change.
-
 Agent skills for Adobe Commerce App Management, following the [agentskills.io](https://agentskills.io) open standard. Compatible with Claude Code, Cursor, VS Code Copilot, Gemini CLI, and other supported agents.
 
 ## Strategy
@@ -37,67 +35,23 @@ A developer creating an app that needs events and webhooks would run `commerce-a
 **Claude Code plugin:**
 
 ```sh
-/plugin marketplace add adobe/aio-commerce-sdk
-/plugin install commerce-app-management@adobe-aio-commerce-sdk
+/plugin marketplace add adobe/skills
+/plugin install commerce-app-management@adobe-skills
 ```
 
 **Tessl CLI:**
 
 ```sh
-tessl install github:adobe/aio-commerce-sdk --skills commerce-app-management
+tessl install github:adobe/skills --skills commerce-app-management
 ```
 
 **pnpx skills:**
 
 ```sh
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-init
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-eventing
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-webhooks
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-business-config
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-storage
-pnpx skills add adobe/aio-commerce-sdk --skill commerce-app-admin-ui
-```
-
-## Contributing
-
-### Local testing
-
-Install skills directly from a local checkout into a target project:
-
-```sh
-cd ~/my-commerce-app
-
-# Install all skills
-pnpx skills add /path/to/aio-commerce-sdk/plugins/commerce/app-management --yes
-
-# Install a specific skill only
-pnpx skills add /path/to/aio-commerce-sdk/plugins/commerce/app-management --yes --skill commerce-app-init
-```
-
-### Quality review
-
-Before shipping a skill, run the tessl reviewer to catch structural and quality issues:
-
-```sh
-pnpx tessl skill review skills/<skill-name>
+pnpx skills add adobe/skills --skill commerce-app-init
+pnpx skills add adobe/skills --skill commerce-app-eventing
+pnpx skills add adobe/skills --skill commerce-app-webhooks
+pnpx skills add adobe/skills --skill commerce-app-business-config
+pnpx skills add adobe/skills --skill commerce-app-storage
+pnpx skills add adobe/skills --skill commerce-app-admin-ui
 ```
-
-A passing skill has 0 errors and 0 warnings. The judge score should be ≥ 90%.
-
-### Evaluations
-
-Implemented skills ship with evals in `skills/<skill-name>/evals/evals.json`, following the [agentskills.io eval format](https://agentskills.io/skill-creation/evaluating-skills.md).
-
-Install the `skill-creator` skill to automate the eval loop:
-
-```sh
-pnpx skills add anthropics/skills --skill skill-creator
-```
-
-Then ask your agent:
-
-```
-Run evals for the commerce-app-init skill
-```
-
-The agent runs each prompt with and without the skill, grades assertions, and writes results to `skills/<skill-name>-workspace/`. Eval results are excluded from version control — only `evals/evals.json` is committed.
diff --git a/plugins/commerce/app-management/package.json b/plugins/commerce/app-management/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "@adobe/aio-commerce-plugin-app-management",
+  "version": "1.1.4",
+  "private": true,
+  "scripts": {
+    "version": "sdk-sync-plugin-version"
+  },
+  "devDependencies": {
+    "@aio-commerce-sdk/scripts": "workspace:*"
+  }
+}
diff --git a/plugins/commerce/app-management/skills/commerce-app-admin-ui/SKILL.md b/plugins/commerce/app-management/skills/commerce-app-admin-ui/SKILL.md
@@ -17,8 +17,6 @@ compatibility: >
   Requires a base app initialized with commerce-app-init.
 metadata:
   author: adobe
-  sdk-package: "@adobe/aio-commerce-sdk"
-  version: "0.0.5"
 ---
 
 # Configure Commerce App Admin UI

diff --git a/plugins/commerce/app-management/skills/commerce-app-business-config/SKILL.md b/plugins/commerce/app-management/skills/commerce-app-business-config/SKILL.md
@@ -12,8 +12,6 @@ compatibility: >
   Requires a base app initialized with commerce-app-init.
 metadata:
   author: adobe
-  sdk-package: "@adobe/aio-commerce-lib-app"
-  version: "0.0.2"
 ---
 
 # Configure Commerce App Business Config

diff --git a/plugins/commerce/app-management/skills/commerce-app-eventing/SKILL.md b/plugins/commerce/app-management/skills/commerce-app-eventing/SKILL.md
@@ -12,8 +12,6 @@ compatibility: >
   Requires a base app initialized with commerce-app-init.
 metadata:
   author: adobe
-  sdk-package: "@adobe/aio-commerce-lib-app"
-  version: "0.0.2"
 ---
 
 # Configure Commerce App Eventing

diff --git a/plugins/commerce/app-management/skills/commerce-app-init/SKILL.md b/plugins/commerce/app-management/skills/commerce-app-init/SKILL.md
@@ -17,8 +17,6 @@ compatibility: >
   npx skills add adobe/skills --skill appbuilder-project-init -y
 metadata:
   author: adobe
-  sdk-package: "@adobe/aio-commerce-lib-app"
-  version: "0.0.2"
 ---
 
 # Initialize a new Commerce App

diff --git a/plugins/commerce/app-management/skills/commerce-app-webhooks/SKILL.md b/plugins/commerce/app-management/skills/commerce-app-webhooks/SKILL.md
@@ -11,8 +11,6 @@ compatibility: >
   Requires a base app initialized with commerce-app-init.
 metadata:
   author: adobe
-  sdk-package: "@adobe/aio-commerce-lib-app"
-  version: "0.0.2"
 ---
 
 # Configure Commerce App Webhooks

diff --git a/plugins/commerce/app-migration/.claude-plugin/plugin.json b/plugins/commerce/app-migration/.claude-plugin/plugin.json
@@ -6,6 +6,7 @@
     "name": "Adobe",
     "email": "commerce-app-management@adobe.com"
   },
+  "repository": "https://github.com/adobe/aio-commerce-sdk",
   "keywords": [
     "adobe-commerce",
     "app-builder",

diff --git a/plugins/commerce/app-migration/README.md b/plugins/commerce/app-migration/README.md
@@ -1,7 +1,5 @@
 # Commerce App Migration Skills
 
-> ⚠️ **Experimental** — These skills are under active development and subject to change.
-
 Agent skills for migrating Adobe Commerce App Builder projects to the App Management approach, following the [agentskills.io](https://agentskills.io) open standard. Compatible with Claude Code, Cursor, VS Code Copilot, Gemini CLI, and other supported agents.
 
 ## Available skills
@@ -48,18 +46,18 @@ Orchestrates the full migration workflow: project detection → domain analysis
 **Claude Code plugin:**
 
 ```sh
-/plugin marketplace add adobe/aio-commerce-sdk
-/plugin install commerce-app-migration@adobe-aio-commerce-sdk
+/plugin marketplace add adobe/skills
+/plugin install commerce-app-migration@adobe-skills
 ```
 
 **Tessl CLI:**
 
 ```sh
-tessl install github:adobe/aio-commerce-sdk --skills commerce-app-migrate
+tessl install github:adobe/skills --skills commerce-app-migrate
 ```
 
 **npx skills:**
 
 ```sh
-npx skills add adobe/aio-commerce-sdk --skill commerce-app-migrate
+npx skills add adobe/skills --skill commerce-app-migrate
 ```