agent-skill-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skill Collection Deploy

Agent 技能集合部署工具

Purpose

用途

Automate multi-surface deployment of agent skill collections:

Pre-flight validation of git state, skills inventory, and surface readiness
Conventional commit analysis with version bump recommendation
Version bumping across all detected surface configuration files
Surface-specific deployment with dry-run capability
User approval gates before irreversible operations

自动化完成Agent技能集合的多渠道部署：

Git状态、技能清单、渠道就绪性的发布前校验
基于约定式提交分析的版本号升级建议
所有已识别渠道配置文件的版本号统一升级
支持试运行能力的渠道专属部署
不可逆操作前的用户审批闸门

When to Use This Skill

何时使用该技能

Use this skill when the user:

Asks to "release", "deploy", "publish", or "ship" a skills collection
Wants to bump versions and push to one or more marketplaces
Needs to create a GitHub release for a skills repository
Wants to publish skills to Claude Code, VS Code, or Copilot CLI marketplaces
Asks to check deployment readiness or run a dry-run release

Do not use for npm packages, Docker deployments, Azure resource provisioning, or repositories without a

/skills

directory.

当用户出现以下需求时使用本技能：

要求“发布”、“部署”、“上线”或“推送”技能集合
需要升级版本并推送到一个或多个市场
需要为技能仓库创建GitHub Release
需要将技能发布到Claude Code、VS Code或Copilot CLI市场
要求检查部署就绪性或运行试运行版本发布

禁止使用于npm包、Docker部署、Azure资源 provisioning 或不含

/skills

目录的仓库。

Supported Surfaces

支持的分发渠道

Surface	Config Files	Deploy Action	Tool Required
github	Git remote URL	Create tag + GitHub release	`gh`
claude-code	`.claude-plugin/plugin.json` (required), `.claude-plugin/marketplace.json` (optional)	Bump plugin version, commit, push	`git`
vscode	`package.json`	Bump version, commit, push	`git`
copilot-cli	`package.json` , `.github/plugin/plugin.json` , `.github/plugin/marketplace.json` (optional)	Bump plugin version, commit, push	`git`

渠道	配置文件	部署操作	所需工具
github	Git远程地址	创建标签 + GitHub Release	`gh`
claude-code	`.claude-plugin/plugin.json` （必填）、 `.claude-plugin/marketplace.json` （可选）	升级插件版本、提交、推送	`git`
vscode	`package.json`	升级版本、提交、推送	`git`
copilot-cli	`package.json` 、 `.github/plugin/plugin.json` 、 `.github/plugin/marketplace.json` （可选）	升级插件版本、提交、推送	`git`

Bundled Scripts

内置脚本

This skill includes three Node.js helper scripts in

scripts/

for cross-platform operation (Windows and macOS):

deploy-preflight.mjs — Validates git state, discovers surfaces, checks tool availability, verifies version consistency (including git tag version)
deploy-analyze.mjs — Inventories skills, analyzes commits since last tag, recommends version bump
deploy-execute.mjs — Bumps versions in all detected config files (regardless of selected surfaces), commits, tags, and deploys to selected surfaces

Run scripts from the skill directory:

bash

node scripts/deploy-preflight.mjs
node scripts/deploy-analyze.mjs
node scripts/deploy-execute.mjs 1.2.0 --surfaces github,claude-code --dry-run

本技能在

scripts/

目录下包含3个Node.js辅助脚本，支持跨平台运行（Windows和macOS）：

deploy-preflight.mjs — 校验Git状态、识别分发渠道、检查工具可用性、验证版本一致性（含Git标签版本）
deploy-analyze.mjs — 清点技能清单、分析上个标签以来的提交、给出版本升级建议
deploy-execute.mjs — 升级所有已识别配置文件的版本（无论选择哪些渠道）、提交、打标签、部署到选中的渠道

在技能目录下运行脚本：

bash

node scripts/deploy-preflight.mjs
node scripts/deploy-analyze.mjs
node scripts/deploy-execute.mjs 1.2.0 --surfaces github,claude-code --dry-run

Version Handling Rules

版本处理规则

Marketplace.json files contain two distinct version fields with different semantics:

plugins[].version
(plugin version) — Tracks the version of each listed plugin. Bumped during releases for local plugins (where
```
source
```
is
```
"."
```
).
metadata.version
(marketplace version) — Tracks the version of the marketplace collection itself. Never bumped during skill/plugin releases. Managed independently.

Cross-file sync rules:

All plugin versions must stay consistent:
```
plugin.json
```
,
```
package.json
```
,
```
plugins[].version
```
in marketplace files, and the git tag.
All
```
metadata.version
```
values across marketplace.json files (
```
.claude-plugin/marketplace.json
```
and
```
.github/plugin/marketplace.json
```
) must stay in sync with each other.

Marketplace.json文件包含两个语义不同的版本字段：

plugins[].version
（插件版本） — 跟踪每个列出插件的版本，发布本地插件（
```
source
```
为
```
"."
```
）时升级该字段
metadata.version
（市场版本） — 跟踪市场集合本身的版本，技能/插件发布时永远不升级该字段，需独立管理

跨文件同步规则：

所有插件版本必须保持一致：包括
```
plugin.json
```
、
```
package.json
```
、市场文件中的
```
plugins[].version
```
以及Git标签

所有marketplace.json文件（

.claude-plugin/marketplace.json

和

.github/plugin/marketplace.json

）的

metadata.version

值必须互相保持同步

Deploy Workflow

部署工作流

Follow these steps in order. Stop immediately if any step fails.

请按顺序执行以下步骤，任意步骤失败时立即停止。

Step 1: Pre-flight Checks

步骤1：发布前检查

Run the preflight script to validate readiness:

bash

node scripts/deploy-preflight.mjs

This checks:

Current directory is a git repository
Current branch is
```
master
```
or
```
main
```
Working tree is clean (no uncommitted changes)
```
/skills
```
directory exists and contains at least one skill
Detects which surfaces are configured based on existing config files
Verifies required tools are available for each surface
Checks that both
```
.claude-plugin/plugin.json
```
and
```
.github/plugin/plugin.json
```
exist; warns if either is missing (auto-created during deploy)
Reports version consistency across all surface configs, including git tag version

If checks fail, report the problem and suggest a fix. Do not proceed.

运行预检脚本验证就绪性：

bash

node scripts/deploy-preflight.mjs

检查内容包括：

当前目录是Git仓库
当前分支为
```
master
```
或
```
main
```
工作树干净（无未提交变更）
```
/skills
```
目录存在且包含至少一个技能
根据现有配置文件识别已配置的分发渠道
验证每个渠道所需工具是否可用
检查
```
.claude-plugin/plugin.json
```
和
```
.github/plugin/plugin.json
```
是否存在；任一缺失时给出警告（部署过程中会自动创建）
报告所有渠道配置的版本一致性，包括Git标签版本

如果检查失败，报告问题并给出修复建议，不要继续执行。

Step 2: Analyze Changes

步骤2：变更分析

Run the analysis script to understand what changed:

bash

node scripts/deploy-analyze.mjs

This will:

Inventory all skills in
```
/skills
```
with their names
Find the last release tag (or handle first release)
List all commits since that tag
Count commits by conventional type using anchored regex
Detect breaking changes (
```
type!:
```
suffix or
```
BREAKING CHANGE
```
in body)
Show file change statistics
Print a version bump recommendation

Version bump criteria:

Bump	When
Major	Breaking changes — `type!:` prefix or `BREAKING CHANGE` body
Minor	New features — any `feat:` commits
Patch	Everything else — `fix:` , `docs:` , `refactor:` , `chore:` , etc.

运行分析脚本了解变更内容：

bash

node scripts/deploy-analyze.mjs

该脚本会执行以下操作：

清点
```
/skills
```
目录下所有技能及其名称
找到最新的发布标签（或处理首次发布场景）
列出该标签以来的所有提交
使用锚定正则按约定式提交类型统计提交数量
检测破坏性变更（
```
type!:
```
后缀或正文包含
```
BREAKING CHANGE
```
）
展示文件变更统计
输出版本升级建议

版本升级标准：

升级类型	触发条件
Major	破坏性变更 — 带 `type!:` 前缀或正文包含 `BREAKING CHANGE`
Minor	新增功能 — 存在任意 `feat:` 类型提交
Patch	其他所有变更 — `fix:` 、 `docs:` 、 `refactor:` 、 `chore:` 等类型提交

Step 2b: Build Per-Skill Changelog

步骤2b：构建单技能变更日志

When the github surface is selected, build a concise, human-readable changelog grouped by skill. This replaces GitHub's auto-generated notes.

Procedure:

Identify the previous release tag from
```
deploy-analyze.mjs
```
output (the
```
Last release tag
```
line). If this is the first release, compare against the root commit.

For each skill listed in the

Skills Changed

output, run:

bash

git diff v{{PREVIOUS}}..HEAD -- skills/{{SKILL_NAME}}/

Analyze each diff and produce a concise bullet list summarizing user-visible changes per skill. Guidelines:
- Write each bullet as a short, action-oriented statement (e.g., "Added X", "Fixed Y", "Removed Z").
- Group by skill as a level-2 heading (
```
## skill-name
```
  ).
- Omit internal-only changes (whitespace, line-ending normalization) unless they are the only change.
- Mention version bumps within skill metadata only if no other substantive changes exist for that skill.
- Cap at roughly 5–7 bullets per skill; combine minor items if needed.
Store the assembled Markdown changelog text for use in Step 9.

Example output format:

markdown

undefined

当选中github渠道时，构建按技能分组的简洁、易读的变更日志，替代GitHub自动生成的发布说明。

操作流程：

从
```
deploy-analyze.mjs
```
的输出中找到上一个发布标签（
```
Last release tag
```
行），如果是首次发布，则和根提交对比。

对

Skills Changed

输出中列出的每个技能，运行：

bash

git diff v{{PREVIOUS}}..HEAD -- skills/{{SKILL_NAME}}/

分析每个diff，生成简洁的项目符号列表，总结每个技能的用户可见变更，规范：
- 每个项目符号写成简短的面向操作的语句（例如“新增X”、“修复Y”、“移除Z”）
- 按技能分组作为二级标题（
```
## 技能名称
```
  ）
- 忽略仅内部的变更（空格、换行符规范化），除非这是唯一的变更
- 仅当技能没有其他实质性变更时，才提及技能元数据内的版本升级
- 每个技能最多保留约5-7个项目符号，必要时合并次要变更
保存组装好的Markdown变更日志文本，供步骤9使用

输出格式示例：

markdown

undefined

agent-package-manager

Added subdirectory path and pinned tag dependency examples to template
Expanded manifest reference with Azure DevOps and GitLab guidance
Added "APM not installed" troubleshooting section

为模板新增子目录路径和固定标签依赖示例
扩展manifest参考文档，新增Azure DevOps和GitLab指引
新增“APM未安装”故障排查章节

agent-skill-deploy

Made marketplace.json optional for Claude Code surface detection
Simplified version bump recommendation logic

让Claude Code渠道检测时marketplace.json为可选
简化版本升级建议逻辑

github-agentic-workflows

Added install.md URL reference for agent-assisted setup


If only a single skill changed, omit the heading and use a flat bullet list.

新增install.md URL参考，支持Agent辅助安装


如果仅单个技能发生变更，省略标题，直接使用平铺的项目符号列表。

Step 3: Confirm Version and Surfaces with User

步骤3：向用户确认版本和分发渠道

Present the analysis summary and ask the user to choose a version and target surfaces.

Use the AskUserQuestion tool for version:

AskUserQuestion:
  question: "Recommended: {{RECOMMENDATION}}. Which version bump for v{{CURRENT}} → v{{NEXT}}?"
  header: "Version"
  options:
    - label: "Major (v{{MAJOR}})"
      description: "Breaking changes — skill removals, renames, config restructuring"
    - label: "Minor (v{{MINOR}})"
      description: "New features — new skills, significant enhancements"
    - label: "Patch (v{{PATCH}})"
      description: "Fixes, docs, refactoring, chore, CI, tests"
    - label: "Cancel"
      description: "Abort the deployment"

Replace

{{CURRENT}}

with current version, compute

{{MAJOR}}

{{MINOR}}

{{PATCH}}

by incrementing the relevant segment (reset lower segments to 0).

If user selects Cancel, stop the workflow.

Use the AskUserQuestion tool for surfaces:

AskUserQuestion:
  question: "Detected surfaces: {{DETECTED_SURFACES}}. Which surfaces to deploy to?"
  header: "Surfaces"
  options:
    - label: "All detected ({{DETECTED_SURFACES}})"
      description: "Deploy to every surface that has config files"
    - label: "GitHub release only"
      description: "Create tag and GitHub release"
    - label: "Marketplaces only"
      description: "Update marketplace configs without GitHub release"
    - label: "Custom selection"
      description: "Specify exact surfaces"
    - label: "Cancel"
      description: "Abort the deployment"

展示分析摘要，要求用户选择版本和目标分发渠道。

使用AskUserQuestion工具确认版本：

AskUserQuestion:
  question: "建议版本：{{RECOMMENDATION}}。v{{CURRENT}} → v{{NEXT}}选择哪个版本升级类型？"
  header: "版本"
  options:
    - label: "Major (v{{MAJOR}})"
      description: "破坏性变更 — 技能移除、重命名、配置结构调整"
    - label: "Minor (v{{MINOR}})"
      description: "新增功能 — 新增技能、重大功能增强"
    - label: "Patch (v{{PATCH}})"
      description: "修复、文档更新、重构、杂项、CI、测试"
    - label: "取消"
      description: "终止部署"

将

{{CURRENT}}

替换为当前版本，通过递增对应版本段计算

{{MAJOR}}

、

{{MINOR}}

、

{{PATCH}}

（低位段重置为0）。

如果用户选择取消，停止工作流。

使用AskUserQuestion工具确认分发渠道：

AskUserQuestion:
  question: "已识别渠道：{{DETECTED_SURFACES}}。要部署到哪些渠道？"
  header: "分发渠道"
  options:
    - label: "所有已识别渠道 ({{DETECTED_SURFACES}})"
      description: "部署到所有存在配置文件的渠道"
    - label: "仅GitHub Release"
      description: "创建标签和GitHub Release"
    - label: "仅市场"
      description: "更新市场配置，不创建GitHub Release"
    - label: "自定义选择"
      description: "指定具体渠道"
    - label: "取消"
      description: "终止部署"

Step 4: Dry Run (Recommended)

步骤4：试运行（推荐）

Before making changes, perform a dry run to verify what will happen:

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --dry-run

Present the dry-run output to the user. The dry run shows:

Which files will be modified and how
Which git operations will be performed
Which surface-specific deploy commands will run
No files are changed, no git operations are executed

If the dry run reveals issues, address them before proceeding.

在做实际变更前，执行试运行验证操作内容：

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --dry-run

向用户展示试运行输出，试运行会展示：

哪些文件会被修改、如何修改
会执行哪些Git操作
会运行哪些渠道专属部署命令
不会修改任何文件、不会执行任何Git操作

如果试运行发现问题，先解决问题再继续。

Step 5: Bump Versions

步骤5：升级版本

Execute the version bump across all detected surface configs:

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --bump-only

IMPORTANT — version sync invariant: The script always bumps every detected config file (plugin.json, marketplace.json, package.json) regardless of which surfaces were selected via

--surfaces

. This prevents version drift between surfaces. The

--surfaces

flag only controls which deployment actions run in

--push

mode.

Auto-creation of missing plugin.json: Before bumping, the script checks that both

.claude-plugin/plugin.json

(claude-code surface) and

.github/plugin/plugin.json

(copilot-cli surface) exist. If either file is missing, it is automatically created from the sibling plugin.json (preferred) or from

package.json

metadata (name, description, version, author, repository, license, keywords) as a fallback. The copilot-cli variant also gets

"skills": "skills/"

This updates version fields in:

```
.claude-plugin/plugin.json
```
→
```
.version
```
(claude-code surface)

.claude-plugin/marketplace.json

→

.plugins[0].version

(claude-code surface, only if the file exists)

```
package.json
```
→
```
.version
```
(vscode and copilot-cli surfaces)
```
.github/plugin/plugin.json
```
→
```
.version
```
(copilot-cli surface, only if the file exists)

.github/plugin/marketplace.json

→

.plugins[0].version

and

.metadata.version

(copilot-cli surface, only if the file exists)

marketplace.json

is absent, the plugin is assumed to be listed by a marketplace defined in another repository. Only

plugin.json

is bumped.

Verify all files were updated correctly by reading them back.

在所有已识别的渠道配置中执行版本升级：

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --bump-only

重要 — 版本同步规则： 无论通过

--surfaces

选择了哪些渠道，脚本总会升级所有已识别的配置文件（plugin.json、marketplace.json、package.json），避免渠道间版本漂移。

--surfaces

参数仅控制

--push

模式下运行哪些部署操作。

自动创建缺失的plugin.json： 升级前，脚本会检查

.claude-plugin/plugin.json

（claude-code渠道）和

.github/plugin/plugin.json

（copilot-cli渠道）是否存在。任一文件缺失时，会自动从另一个同类型plugin.json（优先）或

package.json

元数据（名称、描述、版本、作者、仓库、许可证、关键词）为 fallback 创建。copilot-cli版本还会自动添加

"skills": "skills/"

字段。

该操作会更新以下位置的版本字段：

```
.claude-plugin/plugin.json
```
→
```
.version
```
（claude-code渠道）

.claude-plugin/marketplace.json

→

.plugins[0].version

（claude-code渠道，仅文件存在时）

```
package.json
```
→
```
.version
```
（vscode和copilot-cli渠道）
```
.github/plugin/plugin.json
```
→
```
.version
```
（copilot-cli渠道，仅文件存在时）

.github/plugin/marketplace.json

→

.plugins[0].version

和

.metadata.version

（copilot-cli渠道，仅文件存在时）

如果

marketplace.json

不存在，则假设插件在其他仓库定义的市场中列出，仅升级

plugin.json

。

通过回读文件验证所有文件都已正确更新。

Step 6: Commit Version Bump

步骤6：提交版本升级

Stage and commit all modified config files:

bash

git add -A
git commit -m "Release v{{VERSION}}"

暂存并提交所有修改的配置文件：

bash

git add -A
git commit -m "Release v{{VERSION}}"

Step 7: Create Git Tag

步骤7：创建Git标签

Tag the release commit:

bash

git tag v{{VERSION}}

为发布提交打标签：

bash

git tag v{{VERSION}}

Step 8: User Approval Before Push

步骤8：推送前用户审批

CRITICAL: Always pause here for user approval.

Present a summary and ask for confirmation.

Use the AskUserQuestion tool:

AskUserQuestion:
  question: "Ready to push v{{VERSION}} and deploy to {{SURFACES}}?"
  header: "Deploy"
  options:
    - label: "Yes — push and deploy"
      description: "Push commits, tags, and run surface-specific deployments"
    - label: "Push only — skip surface deploys"
      description: "Push commits and tags but skip marketplace-specific actions"
    - label: "No — keep local"
      description: "Keep local commit and tag, do not push"

If user selects No, inform them:

The commit and tag remain local

To undo:

git reset --hard HEAD~1 && git tag -d v{{VERSION}}

关键：此处必须暂停等待用户审批。

展示摘要并请求确认。

使用AskUserQuestion工具：

AskUserQuestion:
  question: "准备好推送v{{VERSION}}并部署到{{SURFACES}}了吗？"
  header: "部署"
  options:
    - label: "是 — 推送并部署"
      description: "推送提交、标签，并运行渠道专属部署"
    - label: "仅推送 — 跳过渠道部署"
      description: "推送提交和标签，但跳过市场专属操作"
    - label: "否 — 保留本地变更"
      description: "保留本地提交和标签，不推送"

如果用户选择否，告知用户：

提交和标签仍保留在本地

撤销方法：

git reset --hard HEAD~1 && git tag -d v{{VERSION}}

Step 9: Push and Deploy

步骤9：推送并部署

Only after user approves:

Save the per-skill changelog from Step 2b to a temporary file:
bash
```
echo '{{CHANGELOG}}' > /tmp/release-notes.md
```

Run the push and deploy:

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --push --notes-file /tmp/release-notes.md

This performs:

```
git push && git push --tags
```
for all surfaces
For github surface: create the release using the per-skill changelog from Step 2b:
bash
```
gh release create v{{VERSION}} --title "v{{VERSION}}" --notes-file /tmp/release-notes.md
```
If
```
--notes-file
```
is not provided, the script falls back to
```
--generate-notes
```
. Always prefer providing the per-skill changelog.

After pushing, print the remote URL and relevant marketplace links.

仅在用户批准后执行：

将步骤2b生成的单技能变更日志保存到临时文件：
bash
```
echo '{{CHANGELOG}}' > /tmp/release-notes.md
```

运行推送和部署：

bash

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --push --notes-file /tmp/release-notes.md

该操作会执行：

为所有渠道执行
```
git push && git push --tags
```
针对github渠道：使用步骤2b生成的单技能变更日志创建Release：
bash
```
gh release create v{{VERSION}} --title "v{{VERSION}}" --notes-file /tmp/release-notes.md
```
如果未提供
```
--notes-file
```
，脚本会回退到
```
--generate-notes
```
，优先使用自定义的单技能变更日志。

推送完成后，输出远程地址和相关市场链接。

Error Handling

错误处理

No
/skills
directory: Report that the repository does not follow the expected skill collection layout and stop.
Missing tools: Report which tools are missing for which surfaces. Suggest installation commands. Allow deployment to surfaces whose tools are available.
Version mismatch across surfaces: Report the mismatch and suggest running the bump step to synchronize all config files.
Tag already exists: Report the conflict and suggest either choosing a different version or deleting the existing tag with user confirmation.
Push failure: Report the error. Do not retry automatically. Suggest checking remote access and authentication.
Surface deploy failure: If one surface fails, report it but continue with remaining surfaces. Provide per-surface status summary at the end.
Dry-run divergence: If the actual execution differs from the dry run, pause and report the divergence to the user.

无
/skills
目录：报告仓库不符合预期的技能集合布局，停止执行
工具缺失： 报告哪些渠道缺少哪些工具，给出安装命令，允许部署到工具已就绪的渠道
渠道间版本不匹配： 报告不匹配问题，建议运行升级步骤同步所有配置文件
标签已存在： 报告冲突，建议选择其他版本或经用户确认后删除现有标签
推送失败： 报告错误，不要自动重试，建议检查远程访问权限和认证
渠道部署失败： 如果单个渠道部署失败，报告问题但继续执行剩余渠道的部署，最后输出每个渠道的状态摘要
实际执行与试运行不一致： 暂停并向用户报告不一致问题