agent-skill-deploy

Agent Skill Collection Deploy

用途

自动完成 Agent 技能集合在多个平台上的部署：

• 预检 Git 状态、技能清单和各平台的就绪情况
• 分析 Conventional Commits，并建议版本升级
• 在所有检测到的平台配置文件中升级版本
• 针对特定平台部署，并支持试运行
• 在不可逆操作前设置用户审批关卡

何时使用此技能

在以下情况下使用此技能：

• 用户要求“发布”“部署”或“推出”技能集合
• 用户想升级版本并推送到一个或多个市场
• 用户需要为技能仓库创建 GitHub 发布版本
• 用户想将技能发布到 Claude Code、VS Code 或 Copilot CLI 市场
• 用户要求检查部署就绪情况或进行发布试运行

请勿用于 npm 包、Docker 部署、Azure 资源预配，或不包含 /skills 目录的仓库。

支持的平台

平台	配置文件	部署操作	所需工具
github	Git 远程 URL	创建标签 + GitHub 发布版本	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

附带脚本

此技能包含三个 Node.js 辅助脚本，位于 scripts/ 中，可跨平台运行（Windows 和 macOS）：

1. deploy-preflight.mjs — 验证 Git 状态、发现平台、检查工具是否可用，并确认版本一致性（包括 Git 标签版本）
2. deploy-analyze.mjs — 汇总技能清单，分析自上个标签以来的提交，并建议版本升级
3. deploy-execute.mjs — 升级所有已检测到的配置文件中的版本（无论选择了哪些平台），然后提交、打标签并部署到所选平台

从技能目录运行脚本：

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

版本处理规则

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 值必须彼此保持同步。

部署工作流

按顺序执行以下步骤。任何步骤失败时都应立即停止。

第 1 步：部署前检查

运行预检脚本，验证是否已准备就绪：

node scripts/deploy-preflight.mjs

此脚本会检查：

• 当前目录是否为 git 仓库
• 当前分支是否为 master 或 main
• 工作树是否干净（没有未提交的更改）
• /skills 目录是否存在且至少包含一个技能
• 根据现有配置文件检测已配置的发布平台
• 验证每个平台所需的工具是否可用
• 检查 .claude-plugin/plugin.json 和 .github/plugin/plugin.json 是否都存在；如果缺少其中任一个，会发出警告（部署时会自动创建）
• 报告所有平台配置中的版本是否一致，包括 git 标签版本

如果检查失败，请报告问题并建议修复方法。不要继续。

第 2 步：分析更改

运行分析脚本，了解发生了哪些更改：

node scripts/deploy-analyze.mjs

此脚本会：

• 列出 /skills 中所有技能的名称
• 找出上一个发布标签（或处理首次发布）
• 列出自该标签以来的所有提交
• 使用锚定正则表达式按 Conventional Commits 类型统计提交
• 检测破坏性更改（type!: 后缀或正文中的 BREAKING CHANGE）
• 显示文件更改统计信息
• 提供版本递增建议

版本递增标准：

递增类型	条件
Major	破坏性更改——type!: 前缀或正文中的 BREAKING CHANGE
Minor	新功能——任何 feat: 提交
Patch	其他所有情况——fix:、docs:、refactor:、chore: 等

第 2b 步：生成按技能分类的更新日志

选择 github 发布平台时，生成一份简洁、易读且按技能分类的更新日志，替代 GitHub 自动生成的说明。

流程：

1. 从 deploy-analyze.mjs 的输出中找到上一个发布标签（Last release tag 行）。如果是首次发布，则与根提交进行比较。
2. 对于 Skills Changed 输出中列出的每个技能，运行：

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

3. 分析每个差异，并按技能生成简洁的项目符号列表，概述用户可见的更改。指南：
   • 每条项目符号应为简短、以操作为导向的描述（例如，“添加了 X”“修复了 Y”“移除了 Z”）。
   • 按技能分组，使用二级标题（## skill-name）。
   • 省略仅限内部的更改（空白字符、行尾规范化），除非这是唯一的更改。
   • 仅当某个技能没有其他实质性更改时，才提及技能元数据中的版本递增。
   • 每个技能最多约 5–7 条；必要时可合并次要项目。
4. 保存整理完成的 Markdown 更新日志文本，以供第 9 步使用。

输出格式示例：

## 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

## agent-skill-deploy
- Made marketplace.json optional for Claude Code surface detection
- Simplified version bump recommendation logic

## github-agentic-workflows
- Added install.md URL reference for agent-assisted setup

如果只更改了一个技能，则省略标题，使用平铺的项目符号列表。

第 3 步：与用户确认版本和发布平台

展示分析摘要，并询问用户选择版本和目标发布平台。

使用 AskUserQuestion 工具询问版本：

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"

将 {{CURRENT}} 替换为当前版本，递增相应的版本号段来计算 {{MAJOR}}、{{MINOR}}、{{PATCH}}（将更低的版本号段重置为 0）。

如果用户选择 Cancel，则停止工作流。

使用 AskUserQuestion 工具询问发布平台：

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"

第 4 步：试运行（推荐）

在进行更改前，执行试运行，确认将要执行的操作：

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

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

• 将修改哪些文件以及如何修改
• 将执行哪些 git 操作
• 将运行哪些平台专用部署命令
• 不会更改任何文件，也不会执行任何 git 操作

如果试运行发现问题，请在继续之前解决。

第 5 步：更新版本

在所有检测到的配置文件中执行版本更新：

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 中的元数据（name、description、version、author、repository、license、keywords）创建文件，作为备用方案。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。

重新读取所有文件，验证它们是否已正确更新。

第 6 步：提交版本更新

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

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

第 7 步：创建 Git 标签

为发布提交创建标签：

git tag v{{VERSION}}

第 8 步：推送前征求用户批准

关键：务必在此处暂停并征求用户批准。

提供摘要并请求确认。

使用 AskUserQuestion 工具：

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"

如果用户选择否，请告知他们：

• 提交和标签仍保留在本地
• 撤销方法：git reset --hard HEAD~1 && git tag -d v{{VERSION}}

第 9 步：推送并部署

仅在用户批准后执行：

1. 将第 2b 步中每个技能的变更日志保存到临时文件：

   echo '{{CHANGELOG}}' > /tmp/release-notes.md
   

2. 运行推送和部署：

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

此操作会执行：

1. 对所有界面运行 git push && git push --tags
2. 对于 github 界面，使用第 2b 步中每个技能的变更日志创建发布：

   gh release create v{{VERSION}} --title "v{{VERSION}}" --notes-file /tmp/release-notes.md
   

   如果未提供 --notes-file，脚本会回退到 --generate-notes。务必优先提供每个技能的变更日志。

推送后，打印远程 URL 和相关市场链接。

错误处理

• **没有 /skills 目录：**报告该仓库不符合预期的技能集合布局，并停止。
• **缺少工具：**报告哪些界面缺少哪些工具。建议安装命令。允许部署到工具可用的界面。
• **不同界面之间的版本不匹配：**报告不匹配情况，并建议运行版本更新步骤以同步所有配置文件。
• **标签已存在：**报告冲突，并建议选择其他版本，或在用户确认后删除现有标签。
• **推送失败：**报告错误。不要自动重试。建议检查远程访问和身份验证。
• **界面部署失败：**如果某个界面失败，报告失败情况，但继续处理其余界面。最后提供各界面的状态摘要。
• **试运行结果不一致：**如果实际执行与试运行不同，暂停并向用户报告差异。