waynebaby · waynebaby · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
diff --git a/.github/workflows/release-nuget-beta.yml b/.github/workflows/release-nuget-beta.yml
@@ -13,6 +13,7 @@ env:
   DOTNET_VERSION: 9.0.x
   PACKAGE_ID: SubtitleExtractslator.Cli
   PROJECT_PATH: SubtitleExtractslator.Cli/SubtitleExtractslator.Cli.csproj
+  SKILL_PACKAGE_NAME: subtitle-extractslator-skill.zip
 
 jobs:
   release-beta:
@@ -105,6 +106,22 @@ jobs:
           cp "artifacts/nuget/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg" "artifacts/fallback/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg"
           cp "artifacts/nuget/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg" "artifacts/fallback/${PACKAGE_ID}.latest.nupkg"
 
+      - name: Prepare skill package artifact
+        shell: bash
+        run: |
+          set -euo pipefail
+          SKILL_ROOT="artifacts/skill/subtitle-extractslator"
+          rm -rf artifacts/skill
+          rm -f "artifacts/fallback/${SKILL_PACKAGE_NAME}"
+          mkdir -p "${SKILL_ROOT}/references" "${SKILL_ROOT}/assets/so-workflow"
+          cp .github/skills/subtitle-extractslator/SKILL.md "${SKILL_ROOT}/SKILL.md"
+          cp -R .github/skills/subtitle-extractslator/references/. "${SKILL_ROOT}/references/"
+          cp -R .github/skills/subtitle-extractslator/assets/so-workflow/. "${SKILL_ROOT}/assets/so-workflow/"
+          (
+            cd artifacts/skill
+            zip -qr "../fallback/${SKILL_PACKAGE_NAME}" subtitle-extractslator
+          )
+
       - name: Publish beta fallback release
         uses: softprops/action-gh-release@v2
         with:
@@ -115,6 +132,7 @@ jobs:
           files: |
             artifacts/fallback/${{ env.PACKAGE_ID }}.${{ steps.version.outputs.package_version }}.nupkg
             artifacts/fallback/${{ env.PACKAGE_ID }}.latest.nupkg
+            artifacts/fallback/${{ env.SKILL_PACKAGE_NAME }}
 
       - name: Push package to NuGet
         shell: bash

diff --git a/.github/workflows/release-nuget-stable.yml b/.github/workflows/release-nuget-stable.yml
@@ -13,6 +13,7 @@ env:
   DOTNET_VERSION: 9.0.x
   PACKAGE_ID: SubtitleExtractslator.Cli
   PROJECT_PATH: SubtitleExtractslator.Cli/SubtitleExtractslator.Cli.csproj
+  SKILL_PACKAGE_NAME: subtitle-extractslator-skill.zip
 
 jobs:
   release-stable:
@@ -96,6 +97,22 @@ jobs:
           cp "artifacts/nuget/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg" "artifacts/fallback/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg"
           cp "artifacts/nuget/${PACKAGE_ID}.${PACKAGE_VERSION}.nupkg" "artifacts/fallback/${PACKAGE_ID}.latest.nupkg"
 
+      - name: Prepare skill package artifact
+        shell: bash
+        run: |
+          set -euo pipefail
+          SKILL_ROOT="artifacts/skill/subtitle-extractslator"
+          rm -rf artifacts/skill
+          rm -f "artifacts/fallback/${SKILL_PACKAGE_NAME}"
+          mkdir -p "${SKILL_ROOT}/references" "${SKILL_ROOT}/assets/so-workflow"
+          cp .github/skills/subtitle-extractslator/SKILL.md "${SKILL_ROOT}/SKILL.md"
+          cp -R .github/skills/subtitle-extractslator/references/. "${SKILL_ROOT}/references/"
+          cp -R .github/skills/subtitle-extractslator/assets/so-workflow/. "${SKILL_ROOT}/assets/so-workflow/"
+          (
+            cd artifacts/skill
+            zip -qr "../fallback/${SKILL_PACKAGE_NAME}" subtitle-extractslator
+          )
+
       - name: Publish stable fallback release
         uses: softprops/action-gh-release@v2
         with:
@@ -106,6 +123,7 @@ jobs:
           files: |
             artifacts/fallback/${{ env.PACKAGE_ID }}.${{ steps.version.outputs.package_version }}.nupkg
             artifacts/fallback/${{ env.PACKAGE_ID }}.latest.nupkg
+            artifacts/fallback/${{ env.SKILL_PACKAGE_NAME }}
 
       - name: Push package to NuGet
         shell: bash

diff --git a/README.md b/README.md
@@ -15,10 +15,10 @@ It is built for end-to-end subtitle processing: detect existing tracks, search c
 
 ## Downloads
 
-Quick install skill command:
+Quick install packaged skill command:
 
 ```bash
-npx skills add waynebaby/SubtitleExtractslator
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip
 ```
 
 Primary runtime distribution now uses the `SubtitleExtractslator.Cli` NuGet package plus a portable DLL entry outside the skill folder.
@@ -94,13 +94,14 @@ This skill is now enhanced with **SkillOrchestrator deterministic workflow** sup
 
 ## First: Guide-First Runtime Entry
 
-If your goal is to run this as a skill in your own agent, keep `npx skills add` for discovery, and use NuGet package runtime as command source of truth.
+If your goal is to run this as a skill in your own agent, install the packaged skill zip from Releases instead of relying on repo-root discovery, and use NuGet package runtime as command source of truth.
 
-1. Install package from stable/beta channel.
-2. Resolve an absolute DLL path from the restored or extracted package.
-3. Run `dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide` first.
-4. Follow guide command entries for CLI or MCP mode.
-5. If package feed is unavailable, use the fallback `.nupkg` link listed inside the selected package index page.
+1. Add the packaged skill zip from the stable/beta fallback release.
+2. Install runtime package from stable/beta channel.
+3. Resolve an absolute DLL path from the restored or extracted package.
+4. Run `dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide` first.
+5. Follow guide command entries for CLI or MCP mode.
+6. If package feed is unavailable, use the fallback `.nupkg` link listed inside the selected package index page.
 
 Notes:
 
@@ -334,4 +335,3 @@ dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingl
 dotnet publish SubtitleExtractslator.Cli -c Release -r linux-x64 -p:PublishSingleFile=true -p:SelfContained=true
 dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingleFile=true -p:SelfContained=true
 ```
-
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -15,10 +15,10 @@ SubtitleExtractslator 是一个以 skill 为主体的字幕翻译项目。
 
 ## 下载
 
-快捷安装 skill 命令：
+快捷安装打包后的 skill 命令：
 
 ```bash
-npx skills add waynebaby/SubtitleExtractslator
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip
 ```
 
 运行时主交付已经切换为 `SubtitleExtractslator.Cli` NuGet 包 + skill 外部的 portable DLL 入口。
@@ -54,13 +54,14 @@ dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide
 
 ## 先走 Guide-First 入口
 
-如果你的目标是在 agent 中运行此 skill，继续保留 `npx skills add` 作为发现入口，并以 NuGet 运行时与 guide 作为命令真相来源。
+如果你的目标是在 agent 中运行此 skill，请改为安装 Releases 中打包好的 skill zip，而不是依赖仓库根目录发现，并以 NuGet 运行时与 guide 作为命令真相来源。
 
-1. 从稳定或 Beta 通道安装 NuGet 包。
-2. 从还原或解包结果里定位绝对 DLL 路径。
-3. 先运行 `dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide`。
-4. 按 guide 中的入口命令执行 CLI 或 MCP。
-5. 包源不可用时，使用所选包索引页中的 fallback `.nupkg` 链接。
+1. 从稳定或 Beta fallback release 添加打包好的 skill zip。
+2. 从稳定或 Beta 通道安装 NuGet 包。
+3. 从还原或解包结果里定位绝对 DLL 路径。
+4. 先运行 `dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide`。
+5. 按 guide 中的入口命令执行 CLI 或 MCP。
+6. 包源不可用时，使用所选包索引页中的 fallback `.nupkg` 链接。
 
 说明：
 
@@ -295,4 +296,3 @@ dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingl
 dotnet publish SubtitleExtractslator.Cli -c Release -r linux-x64 -p:PublishSingleFile=true -p:SelfContained=true
 dotnet publish SubtitleExtractslator.Cli -c Release -r osx-arm64 -p:PublishSingleFile=true -p:SelfContained=true
 ```
-
diff --git a/docs/skill-installation-and-build.md b/docs/skill-installation-and-build.md
@@ -34,10 +34,24 @@ Binary-free rule:
 
 ## Install from Releases (Recommended)
 
-1. Open repository Releases page and download `subtitle-extractslator-vX.Y.Z.zip`.
-2. Unzip and keep the folder name `subtitle-extractslator` unchanged.
-3. Verify the extracted skill folder contains no `assets/bin/` directory.
-4. Acquire the runtime package from the selected package index page and run:
+Use the packaged skill zip produced by the active fallback release workflows instead of repo-root discovery.
+
+Stable:
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip
+```
+
+Beta:
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/subtitle-extractslator-skill.zip
+```
+
+If your installer only accepts a local archive, download the same release asset, unzip it, and keep the folder name `subtitle-extractslator` unchanged.
+
+1. Verify the extracted skill folder contains no `assets/bin/` directory.
+2. Acquire the runtime package from the selected package index page and run:
    - `dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide`
 
 ## Build Locally (Contributor Path)

diff --git a/packages.beta.md b/packages.beta.md
@@ -10,6 +10,14 @@ This page is the canonical runtime acquisition entry for the binary-free `.githu
 dotnet add package SubtitleExtractslator.Cli --version <beta-version>
 ```
 
+## Install Skill Package
+
+Use the packaged skill zip instead of repo-root discovery:
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/subtitle-extractslator-skill.zip
+```
+
 ## Guide First
 
 After restore or `.nupkg` extraction is available, resolve an absolute DLL path and run:
@@ -29,4 +37,5 @@ dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide
 Use fallback only when package feed is unavailable.
 
 - Latest beta fallback release: <https://github.com/waynebaby/SubtitleExtractslator/releases/tag/nuget-beta-latest>
+- Latest beta skill zip: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/subtitle-extractslator-skill.zip>
 - Latest beta `.latest.nupkg`: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/SubtitleExtractslator.Cli.latest.nupkg>
diff --git a/packages.beta.zh-CN.md b/packages.beta.zh-CN.md
@@ -10,6 +10,14 @@
 dotnet add package SubtitleExtractslator.Cli --version <beta-version>
 ```
 
+## 安装 Skill 包
+
+请使用打包后的 skill zip，不要依赖仓库根目录发现：
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/subtitle-extractslator-skill.zip
+```
+
 ## 运行前先看 guide
 
 在还原或解包 `.nupkg` 后，先定位绝对 DLL 路径，再执行：
@@ -29,4 +37,5 @@ dotnet "<absolute-path>/SubtitleExtractslator.Cli.dll" --guide
 仅在包管理源不可用时使用回退通道。
 
 - Beta 通道最新回退 Release: <https://github.com/waynebaby/SubtitleExtractslator/releases/tag/nuget-beta-latest>
+- Beta 通道 skill zip: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/subtitle-extractslator-skill.zip>
 - Beta 通道 `.latest.nupkg`: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-beta-latest/SubtitleExtractslator.Cli.latest.nupkg>
diff --git a/packages.released.md b/packages.released.md
@@ -10,6 +10,14 @@ This page is the canonical runtime acquisition entry for the binary-free `.githu
 dotnet add package SubtitleExtractslator.Cli --version <stable-version>
 ```
 
+## Install Skill Package
+
+Use the packaged skill zip instead of repo-root discovery:
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip
+```
+
 ## Guide First
 
 After restore or `.nupkg` extraction is available, resolve an absolute DLL path and run:
@@ -37,4 +45,5 @@ For released governance references:
 Use fallback only when package feed is unavailable.
 
 - Latest stable fallback release: <https://github.com/waynebaby/SubtitleExtractslator/releases/tag/nuget-stable-latest>
+- Latest stable skill zip: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip>
 - Latest stable `.latest.nupkg`: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/SubtitleExtractslator.Cli.latest.nupkg>
diff --git a/packages.released.zh-CN.md b/packages.released.zh-CN.md
@@ -10,6 +10,14 @@
 dotnet add package SubtitleExtractslator.Cli --version <stable-version>
 ```
 
+## 安装 Skill 包
+
+请使用打包后的 skill zip，不要依赖仓库根目录发现：
+
+```bash
+npx skills add https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip
+```
+
 ## 运行前先看 guide
 
 在还原或解包 `.nupkg` 后，先定位绝对 DLL 路径，再执行：
@@ -27,4 +35,5 @@ SO 增强后的 workflow template 目前仅在 Beta 文档路径中维护。当
 仅在包管理源不可用时使用回退通道。
 
 - 稳定通道最新回退 Release: <https://github.com/waynebaby/SubtitleExtractslator/releases/tag/nuget-stable-latest>
+- 稳定通道 skill zip: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/subtitle-extractslator-skill.zip>
 - 稳定通道 `.latest.nupkg`: <https://github.com/waynebaby/SubtitleExtractslator/releases/download/nuget-stable-latest/SubtitleExtractslator.Cli.latest.nupkg>