commit a4c35a246467391be01b32f66221217ee336eb2b
Author: Walter Cheng <walterpakwai@live.com>
Date:   Fri Jul 17 13:49:49 2026 -0400

    feat: publish generic agent marketplace workflows

diff --git a/.github/workflows/agent-marketplace-ci.yaml b/.github/workflows/agent-marketplace-ci.yaml
new file mode 100644
index 0000000..f14c5c1
--- /dev/null
+++ b/.github/workflows/agent-marketplace-ci.yaml
@@ -0,0 +1,46 @@
+name: Agent marketplace CI
+
+on:
+  workflow_call:
+    inputs:
+      skill_root:
+        description: Canonical skill directory relative to the repository root.
+        required: false
+        type: string
+        default: skills
+      claude_marketplace_file:
+        description: Claude marketplace manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/marketplace.json
+      claude_plugin_file:
+        description: Claude plugin manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/plugin.json
+      codex_plugin_root:
+        description: Codex plugin root relative to the repository root.
+        required: false
+        type: string
+      cursor_plugin_root:
+        description: Cursor plugin root relative to the repository root.
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Validate agent marketplace
+        uses: walter-base/common-workflow/actions/validate-agent-marketplace@master
+        with:
+          skill_root: ${{ inputs.skill_root }}
+          claude_marketplace_file: ${{ inputs.claude_marketplace_file }}
+          claude_plugin_file: ${{ inputs.claude_plugin_file }}
+          codex_plugin_root: ${{ inputs.codex_plugin_root }}
+          cursor_plugin_root: ${{ inputs.cursor_plugin_root }}
diff --git a/.github/workflows/agent-marketplace-preview.yaml b/.github/workflows/agent-marketplace-preview.yaml
new file mode 100644
index 0000000..3e3567d
--- /dev/null
+++ b/.github/workflows/agent-marketplace-preview.yaml
@@ -0,0 +1,91 @@
+name: Agent marketplace preview
+
+on:
+  workflow_call:
+    inputs:
+      skill_root:
+        description: Canonical skill directory relative to the repository root.
+        required: false
+        type: string
+        default: skills
+      claude_marketplace_file:
+        description: Claude marketplace manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/marketplace.json
+      claude_plugin_file:
+        description: Claude plugin manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/plugin.json
+      codex_plugin_root:
+        description: Codex plugin root relative to the repository root.
+        required: false
+        type: string
+      cursor_plugin_root:
+        description: Cursor plugin root relative to the repository root.
+        required: false
+        type: string
+      package_paths:
+        description: Space-separated paths to package into the preview archive.
+        required: false
+        type: string
+        default: skills .claude-plugin .cursor-plugin .agents plugins README.md CHANGELOG.md
+      archive_name:
+        description: Prefix used for the preview archive.
+        required: false
+        type: string
+        default: agent-marketplace
+
+permissions:
+  contents: read
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out pull request
+        uses: actions/checkout@v4
+      - name: Validate agent marketplace
+        uses: walter-base/common-workflow/actions/validate-agent-marketplace@master
+        with:
+          skill_root: ${{ inputs.skill_root }}
+          claude_marketplace_file: ${{ inputs.claude_marketplace_file }}
+          claude_plugin_file: ${{ inputs.claude_plugin_file }}
+          codex_plugin_root: ${{ inputs.codex_plugin_root }}
+          cursor_plugin_root: ${{ inputs.cursor_plugin_root }}
+      - name: Build preview archive
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+          PACKAGE_PATHS: ${{ inputs.package_paths }}
+          ARCHIVE_NAME: ${{ inputs.archive_name }}
+        shell: bash
+        run: |
+          short_sha="${SHA:0:7}"
+          dir="${ARCHIVE_NAME}-pr-${PR_NUMBER}-${short_sha}"
+          mkdir -p "dist/${dir}"
+          for path in ${PACKAGE_PATHS}; do
+            cp -R "$path" "dist/${dir}/"
+          done
+          tar -czf "dist/${dir}.tar.gz" -C dist "${dir}"
+          echo "PREVIEW_ARCHIVE=dist/${dir}.tar.gz" >> "$GITHUB_ENV"
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.archive_name }}-pr-${{ github.event.pull_request.number }}-${{ github.event.pull_request.head.sha }}
+          path: ${{ env.PREVIEW_ARCHIVE }}
+          retention-days: 14
+      - name: Write preview summary
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+          ARCHIVE_NAME: ${{ inputs.archive_name }}
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" <<EOF
+          # ${ARCHIVE_NAME} preview for PR #${PR_NUMBER}
+
+          Preview artifact: `${ARCHIVE_NAME}-pr-${PR_NUMBER}-${SHA}`
+
+          This artifact expires automatically after 14 days. Stable releases are created only after a release PR is merged into the default branch.
+          EOF
diff --git a/.github/workflows/agent-marketplace-release.yaml b/.github/workflows/agent-marketplace-release.yaml
new file mode 100644
index 0000000..b614c78
--- /dev/null
+++ b/.github/workflows/agent-marketplace-release.yaml
@@ -0,0 +1,179 @@
+name: Agent marketplace release
+
+on:
+  workflow_call:
+    inputs:
+      skill_root:
+        description: Canonical skill directory relative to the repository root.
+        required: false
+        type: string
+        default: skills
+      claude_marketplace_file:
+        description: Claude marketplace manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/marketplace.json
+      claude_plugin_file:
+        description: Claude plugin manifest relative to the repository root.
+        required: false
+        type: string
+        default: .claude-plugin/plugin.json
+      codex_plugin_root:
+        description: Codex plugin root relative to the repository root.
+        required: false
+        type: string
+      cursor_plugin_root:
+        description: Cursor plugin root relative to the repository root.
+        required: false
+        type: string
+      release_config_file:
+        description: Release Please configuration file.
+        required: false
+        type: string
+        default: release-please-config.json
+      release_manifest_file:
+        description: Release Please manifest file.
+        required: false
+        type: string
+        default: .release-please-manifest.json
+      package_paths:
+        description: Space-separated paths to package into the release archive.
+        required: false
+        type: string
+        default: skills .claude-plugin .cursor-plugin .agents plugins README.md CHANGELOG.md
+      archive_name:
+        description: Prefix used for the release archive.
+        required: false
+        type: string
+        default: agent-marketplace
+      claude_plugin_name:
+        description: Claude plugin name used in the installation summary.
+        required: false
+        type: string
+        default: marketplace
+      claude_marketplace_name:
+        description: Claude marketplace name used in the installation summary.
+        required: false
+        type: string
+        default: marketplace
+      codex_marketplace_name:
+        description: Codex marketplace name shown in the installation summary.
+        required: false
+        type: string
+        default: marketplace
+      cursor_plugin_name:
+        description: Cursor plugin name shown in the installation summary.
+        required: false
+        type: string
+        default: marketplace
+    secrets:
+      GITHUB_TOKEN:
+        required: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Create or update release PR
+        id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN || github.token }}
+          target-branch: ${{ github.event.repository.default_branch || 'master' }}
+          config-file: ${{ inputs.release_config_file }}
+          manifest-file: ${{ inputs.release_manifest_file }}
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out released version
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+      - name: Validate released marketplace
+        uses: walter-base/common-workflow/actions/validate-agent-marketplace@master
+        with:
+          skill_root: ${{ inputs.skill_root }}
+          claude_marketplace_file: ${{ inputs.claude_marketplace_file }}
+          claude_plugin_file: ${{ inputs.claude_plugin_file }}
+          codex_plugin_root: ${{ inputs.codex_plugin_root }}
+          cursor_plugin_root: ${{ inputs.cursor_plugin_root }}
+      - name: Build release archive
+        env:
+          VERSION: ${{ needs.release-please.outputs.version }}
+          PACKAGE_PATHS: ${{ inputs.package_paths }}
+          ARCHIVE_NAME: ${{ inputs.archive_name }}
+        shell: bash
+        run: |
+          dir="${ARCHIVE_NAME}-${VERSION}"
+          mkdir -p "dist/${dir}"
+          for path in ${PACKAGE_PATHS}; do
+            cp -R "$path" "dist/${dir}/"
+          done
+          tar -czf "dist/${dir}.tar.gz" -C dist "${dir}"
+      - name: Write installation summary
+        env:
+          VERSION: ${{ needs.release-please.outputs.version }}
+          TAG: ${{ needs.release-please.outputs.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+          SERVER_URL: ${{ github.server_url }}
+          CLAUDE_PLUGIN_NAME: ${{ inputs.claude_plugin_name }}
+          CLAUDE_MARKETPLACE_NAME: ${{ inputs.claude_marketplace_name }}
+          CODEX_MARKETPLACE_NAME: ${{ inputs.codex_marketplace_name }}
+          CURSOR_PLUGIN_NAME: ${{ inputs.cursor_plugin_name }}
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" <<EOF
+          # Agent marketplace ${VERSION}
+
+          Released from tag `${TAG}`.
+
+          ## Claude Code
+
+          ```bash
+          claude plugin marketplace add ${REPOSITORY}@${TAG}
+          claude plugin install ${CLAUDE_PLUGIN_NAME}@${CLAUDE_MARKETPLACE_NAME}
+          ```
+
+          ## Codex
+
+          ```bash
+          codex plugin marketplace add ${REPOSITORY} --ref ${TAG}
+          codex
+          # In Codex, run: /plugins and install ${CODEX_MARKETPLACE_NAME}.
+          ```
+
+          ## OpenCode
+
+          ```bash
+          npx skills add ${SERVER_URL}/${REPOSITORY}/tree/${TAG}/${SKILL_ROOT:-skills} --agent opencode --skill '*'
+          ```
+
+          ## Cursor
+
+          ```bash
+          npx skills add ${SERVER_URL}/${REPOSITORY}/tree/${TAG}/${SKILL_ROOT:-skills} --agent cursor --skill '*'
+          ```
+
+          Cursor's native `/add-plugin ${CURSOR_PLUGIN_NAME}` flow can be used after the plugin is published to the Cursor Marketplace.
+          EOF
+      - name: Upload archive to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.release-please.outputs.tag_name }}
+          files: dist/${{ inputs.archive_name }}-*.tar.gz
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..da629a3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,30 @@
+# Common Agent Marketplace Workflows
+
+Public reusable GitHub Actions workflows and validation actions for repositories
+that publish agent skills and plugins.
+
+This repository intentionally contains only generic marketplace automation:
+
+- skill and plugin manifest validation
+- pull-request preview archives
+- release archives and installation summaries
+
+Container, infrastructure, deployment, and environment-specific workflows are
+kept in the private `Walter0697/common-workflow` repository.
+
+## Reuse
+
+Reference the workflows from a repository workflow with a version tag or commit
+SHA, for example:
+
+```yaml
+jobs:
+  validate:
+    uses: walter-base/common-workflow/.github/workflows/agent-marketplace-ci.yaml@master
+```
+
+The validator is also available as:
+
+```yaml
+uses: walter-base/common-workflow/actions/validate-agent-marketplace@master
+```
diff --git a/actions/validate-agent-marketplace/action.yaml b/actions/validate-agent-marketplace/action.yaml
new file mode 100644
index 0000000..101851f
--- /dev/null
+++ b/actions/validate-agent-marketplace/action.yaml
@@ -0,0 +1,33 @@
+name: Validate agent marketplace
+description: Validate Agent Skills and their Claude, Codex, and Cursor distribution bundles.
+inputs:
+  skill_root:
+    description: Root directory containing one skill directory per skill.
+    required: false
+    default: skills
+  claude_marketplace_file:
+    description: Optional Claude marketplace manifest relative to the repository root.
+    required: false
+    default: .claude-plugin/marketplace.json
+  claude_plugin_file:
+    description: Optional Claude plugin manifest relative to the repository root.
+    required: false
+    default: .claude-plugin/plugin.json
+  codex_plugin_root:
+    description: Optional Codex plugin root relative to the repository root.
+    required: false
+  cursor_plugin_root:
+    description: Optional Cursor plugin root relative to the repository root.
+    required: false
+runs:
+  using: composite
+  steps:
+    - name: Validate marketplace
+      shell: bash
+      env:
+        SKILL_ROOT: ${{ inputs.skill_root }}
+        CLAUDE_MARKETPLACE_FILE: ${{ inputs.claude_marketplace_file }}
+        CLAUDE_PLUGIN_FILE: ${{ inputs.claude_plugin_file }}
+        CODEX_PLUGIN_ROOT: ${{ inputs.codex_plugin_root }}
+        CURSOR_PLUGIN_ROOT: ${{ inputs.cursor_plugin_root }}
+      run: "${{ github.action_path }}/validate.sh"
diff --git a/actions/validate-agent-marketplace/validate.sh b/actions/validate-agent-marketplace/validate.sh
new file mode 100755
index 0000000..7eef9e1
--- /dev/null
+++ b/actions/validate-agent-marketplace/validate.sh
@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="${GITHUB_WORKSPACE:-$PWD}"
+skill_root="$repo_root/${SKILL_ROOT:-skills}"
+
+if [[ ! -d "$skill_root" ]]; then
+  echo "ERROR: skill root does not exist: $skill_root" >&2
+  exit 1
+fi
+
+status=0
+count=0
+
+while IFS= read -r skill_file; do
+  count=$((count + 1))
+  skill_dir="$(dirname "$skill_file")"
+  dir_name="$(basename "$skill_dir")"
+  frontmatter_end="$(awk 'NR > 1 && /^---[[:space:]]*$/ { print NR; exit }' "$skill_file")"
+  name="$(awk '
+    NR == 1 { next }
+    /^---[[:space:]]*$/ { exit }
+    /^name:[[:space:]]*/ { sub(/^name:[[:space:]]*/, ""); print; exit }
+  ' "$skill_file")"
+
+  if ! head -1 "$skill_file" | grep -qx -- '---'; then
+    echo "ERROR: $skill_file must start with YAML frontmatter" >&2
+    status=1
+  fi
+  if [[ -z "$frontmatter_end" ]]; then
+    echo "ERROR: $skill_file has no closing frontmatter delimiter" >&2
+    status=1
+  elif ! awk -v end="$frontmatter_end" 'NR > end && $0 !~ /^[[:space:]]*$/ { found=1 } END { exit !found }' "$skill_file"; then
+    echo "ERROR: $skill_file has no instruction body after frontmatter" >&2
+    status=1
+  fi
+  if [[ -z "$name" ]]; then
+    echo "ERROR: $skill_file is missing name" >&2
+  elif [[ "$name" != "$dir_name" ]]; then
+    echo "ERROR: $skill_file name '$name' does not match directory '$dir_name'" >&2
+    status=1
+  elif ! [[ "$name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+    echo "ERROR: $skill_file has invalid name '$name'" >&2
+    status=1
+  fi
+  if ! awk '
+    NR == 1 { next }
+    /^---[[:space:]]*$/ { exit(description_found && description_content ? 0 : 1) }
+    /^description:[[:space:]]*/ {
+      description_found=1
+      value=$0
+      sub(/^description:[[:space:]]*/, "", value)
+      if (value != "" && value !~ /^[>|][+-]?[0-9]*$/) description_content=1
+      next
+    }
+    description_found && $0 ~ /^[[:space:]]+[^[:space:]]/ { description_content=1 }
+    END { exit(description_found && description_content ? 0 : 1) }
+  ' "$skill_file"; then
+    echo "ERROR: $skill_file is missing a non-empty description" >&2
+    status=1
+  fi
+done < <(find "$skill_root" -mindepth 2 -maxdepth 2 -name SKILL.md -print | sort)
+
+if [[ "$count" -eq 0 ]]; then
+  echo "ERROR: no skills found under $skill_root" >&2
+  exit 1
+fi
+
+validate_json_manifest() {
+  local relative_path="$1"
+  local manifest="$repo_root/$relative_path"
+  if [[ ! -f "$manifest" ]]; then
+    return 0
+  fi
+  if ! jq empty "$manifest" >/dev/null; then
+    echo "ERROR: invalid JSON manifest: $relative_path" >&2
+    status=1
+  fi
+}
+
+validate_json_manifest "$CLAUDE_MARKETPLACE_FILE"
+validate_json_manifest "$CLAUDE_PLUGIN_FILE"
+
+validate_plugin_bundle() {
+  local plugin_root_name="$1"
+  local plugin_root="$repo_root/$plugin_root_name"
+  local manifest="$plugin_root/.codex-plugin/plugin.json"
+  local cursor_manifest="$plugin_root/.cursor-plugin/plugin.json"
+  local bundle_skills="$plugin_root/skills"
+
+  if [[ ! -d "$plugin_root" ]]; then
+    echo "ERROR: plugin root does not exist: $plugin_root_name" >&2
+    status=1
+    return
+  fi
+  if [[ ! -d "$bundle_skills" ]]; then
+    echo "ERROR: plugin has no skills directory: $plugin_root_name/skills" >&2
+    status=1
+    return
+  fi
+  if [[ ! -f "$manifest" && ! -f "$cursor_manifest" ]]; then
+    echo "ERROR: plugin has no supported plugin manifest: $plugin_root_name" >&2
+    status=1
+  fi
+  validate_json_manifest "${plugin_root_name}/.codex-plugin/plugin.json"
+  validate_json_manifest "${plugin_root_name}/.cursor-plugin/plugin.json"
+
+  if ! diff -ru "$skill_root" "$bundle_skills" >/dev/null; then
+    echo "ERROR: plugin skills are out of sync with $SKILL_ROOT: $plugin_root_name/skills" >&2
+    status=1
+  fi
+}
+
+if [[ -n "${CODEX_PLUGIN_ROOT:-}" ]]; then
+  validate_plugin_bundle "$CODEX_PLUGIN_ROOT"
+fi
+if [[ -n "${CURSOR_PLUGIN_ROOT:-}" && "${CURSOR_PLUGIN_ROOT}" != "${CODEX_PLUGIN_ROOT:-}" ]]; then
+  validate_plugin_bundle "$CURSOR_PLUGIN_ROOT"
+fi
+
+if [[ "$status" -ne 0 ]]; then
+  exit "$status"
+fi
+echo "Validated $count skills and configured marketplace manifests."