Align release artifacts with versioned tags and document Claude upload/install paths

.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Cyber-Gen",
     "url": "https://github.com/Cyber-Gen"
   },
-  "homepage": "https://github.com/Cyber-Gen/visual-explainer",
-  "repository": "https://github.com/Cyber-Gen/visual-explainer",
+  "homepage": "https://github.com/Cyber-Gen/visual-explainer-skill",
+  "repository": "https://github.com/Cyber-Gen/visual-explainer-skill",
   "license": "MIT",
   "keywords": [
     "explainer",

.github/workflows/release.yml

@@ -60,11 +60,10 @@ jobs:
           [ "$missing" -eq 0 ]
 
       - name: Build plugin zip (explicit allowlist)
-        id: plugin_zip
         run: |
           set -euo pipefail
           version="$(jq -r '.version' .claude-plugin/plugin.json)"
-          zipname="visual-explainer-v${version}.zip"
+          zipname="visual-explainer-plugin-v${version}.zip"
           stage="$(mktemp -d)"
           root="$stage/visual-explainer"
           mkdir -p \
@@ -80,31 +79,58 @@ jobs:
           cp README.md                                                     "$root/README.md"
           cp LICENSE                                                       "$root/LICENSE"
           (cd "$stage" && zip -r "$GITHUB_WORKSPACE/$zipname" visual-explainer)
-          sha="$(sha256sum "$zipname" | awk '{print $1}')"
-          echo "name=$zipname" >> "$GITHUB_OUTPUT"
-          echo "sha=$sha"      >> "$GITHUB_OUTPUT"
+
+      - name: Build standalone skill zip (explicit allowlist)
+        run: |
+          set -euo pipefail
+          version="$(jq -r '.version' .claude-plugin/plugin.json)"
+          zipname="visual-explainer-skill-v${version}.zip"
+          stage="$(mktemp -d)"
+          root="$stage/visual-explainer"
+          mkdir -p \
+            "$root/references" \
+            "$root/examples"
+          cp skills/visual-explainer/SKILL.md                              "$root/SKILL.md"
+          cp skills/visual-explainer/references/design-system.md           "$root/references/"
+          cp skills/visual-explainer/references/visual-snapshot-library.md "$root/references/"
+          cp skills/visual-explainer/references/writing-voice.md           "$root/references/"
+          cp skills/visual-explainer/examples/reference-example.html       "$root/examples/"
+          (cd "$stage" && zip -r "$GITHUB_WORKSPACE/$zipname" visual-explainer)
+
+      - name: Generate checksums
+        run: |
+          set -euo pipefail
+          sha256sum \
+            visual-explainer-plugin-v*.zip \
+            visual-explainer-skill-v*.zip \
+            > release-assets-sha256.txt
 
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
-          ZIP_NAME: ${{ steps.plugin_zip.outputs.name }}
-          ZIP_SHA:  ${{ steps.plugin_zip.outputs.sha }}
           TAG:      ${{ github.ref_name }}
         run: |
           set -euo pipefail
+          version="$(jq -r '.version' .claude-plugin/plugin.json)"
+          plugin_zip="visual-explainer-plugin-v${version}.zip"
+          skill_zip="visual-explainer-skill-v${version}.zip"
           notes_file="$(mktemp)"
           cat > "$notes_file" <<EOF
-          ## Asset
+          ## Assets
 
-          - \`${ZIP_NAME}\` — visual-explainer plugin. Extract and load with \`claude --plugin-dir ./visual-explainer\`, or install via a Claude Code plugin marketplace.
+          - \`${plugin_zip}\` — full plugin bundle with the standalone skill included.
+          - \`${skill_zip}\` — standalone skill bundle for \`~/.claude/skills/\`.
+          - \`release-assets-sha256.txt\` — SHA256 checksums for all attached zip assets.
 
           ## SHA256
 
           \`\`\`
-          ${ZIP_SHA}  ${ZIP_NAME}
+          $(cat release-assets-sha256.txt)
           \`\`\`
           EOF
           gh release create "$TAG" \
-            "$ZIP_NAME" \
+            "$plugin_zip" \
+            "$skill_zip" \
+            "release-assets-sha256.txt" \
             --title "visual-explainer ${TAG}" \
             --notes-file "$notes_file"

README.md

@@ -22,25 +22,68 @@ Two install paths, depending on whether you want the full plugin or just the ski
 
 ### Option 1 — Full plugin (recommended)
 
-Download `visual-explainer-plugin-vX.Y.Z.zip` from the [latest release](https://github.com/Cyber-Gen/visual-explainer/releases/latest), unzip into your Claude Code plugins directory, and enable it. Or, for development, point Claude Code at this repo directly:
+Download `visual-explainer-plugin-vX.Y.Z.zip` from the [latest release](https://github.com/Cyber-Gen/visual-explainer-skill/releases/latest).
+
+#### Upload in Claude.ai / Claude Desktop
+
+Use the same plugin upload flow in Claude.ai and Claude Desktop. Cowork, Chat, and Code should all accept the exact same `plugin.zip`.
+
+1. Download `visual-explainer-plugin-vX.Y.Z.zip`.
+2. Open the plugin installer / upload flow in Claude.ai or Claude Desktop.
+3. Choose **Upload plugin** and select the zip.
+4. Confirm the install and enable `visual-explainer`.
+5. Invoke it normally after install.
+
+#### Claude Code development install
 
 ```bash
-git clone https://github.com/Cyber-Gen/visual-explainer.git
-claude --plugin-dir ./visual-explainer
+git clone https://github.com/Cyber-Gen/visual-explainer-skill.git
+claude --plugin-dir ./visual-explainer-skill
 ```
 
 ### Option 2 — Skill only
 
-Download `visual-explainer-skill-vX.Y.Z.zip` from the [latest release](https://github.com/Cyber-Gen/visual-explainer/releases/latest) and unzip into `~/.claude/skills/`:
+Download `visual-explainer-skill-vX.Y.Z.zip` from the [latest release](https://github.com/Cyber-Gen/visual-explainer-skill/releases/latest).
+
+#### Upload in Claude.ai / Claude Desktop
+
+Use the same skill upload flow in Claude.ai and Claude Desktop. Cowork, Chat, and Code should all accept the exact same `skill.zip`.
+
+1. Download `visual-explainer-skill-vX.Y.Z.zip`.
+2. Open the skill installer / upload flow in Claude.ai or Claude Desktop.
+3. Choose **Upload skill** and select the zip.
+4. Confirm the install and enable `visual-explainer`.
+5. Invoke it normally after install.
+
+#### Claude Code filesystem install
 
 ```bash
 mkdir -p ~/.claude/skills
-curl -L -o /tmp/ve-skill.zip https://github.com/Cyber-Gen/visual-explainer/releases/latest/download/visual-explainer-skill-latest.zip
+VERSION=X.Y.Z
+curl -L -o /tmp/ve-skill.zip "https://github.com/Cyber-Gen/visual-explainer-skill/releases/download/v${VERSION}/visual-explainer-skill-v${VERSION}.zip"
 unzip /tmp/ve-skill.zip -d ~/.claude/skills/
 ```
 
 This drops `~/.claude/skills/visual-explainer/SKILL.md` (plus its `references/` and `examples/`) — exactly the layout Claude Code expects for a standalone skill.
 
+## Releasing
+
+Release tags must match `.claude-plugin/plugin.json` exactly: if the manifest version is `0.1.0`, create the tag `v0.1.0`.
+
+```bash
+VERSION="$(jq -r '.version' .claude-plugin/plugin.json)"
+git tag -a "v${VERSION}" -m "visual-explainer v${VERSION}"
+git push origin "v${VERSION}"
+```
+
+Pushing that tag triggers `.github/workflows/release.yml`, which publishes:
+
+- `visual-explainer-plugin-vX.Y.Z.zip`
+- `visual-explainer-skill-vX.Y.Z.zip`
+- `release-assets-sha256.txt`
+
+If you create the tag in GitHub instead of locally, use the same `vX.Y.Z` name and point it at the commit whose `.claude-plugin/plugin.json` already contains `X.Y.Z`.
+
 ## Invoke
 
 Once installed, the skill can be invoked by either: