Agent Skill Deploy

Agent Skill Collection Deploy

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

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.

Supported Surfaces

Bundled Scripts

This skill includes three Node.js helper scripts in scripts/ for cross-platform operation (Windows and macOS):

1. deploy-preflight.mjs — Validates git state, discovers surfaces, checks tool availability, verifies version consistency (including git tag version)
2. deploy-analyze.mjs — Inventories skills, analyzes commits since last tag, recommends version bump
3. 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:

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.

Deploy Workflow

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

Step 1: Pre-flight Checks

Run the preflight script to validate readiness:

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.

Step 2: Analyze Changes

Run the analysis script to understand what changed:

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:

Step 2b: Build Per-Skill Changelog

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

Procedure:

1. 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.
2. For each skill listed in the Skills Changed output, run: ``bash git diff v{{PREVIOUS}}..HEAD -- skills/{{SKILL_NAME}}/ ``
3. 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.

1. Store the assembled Markdown changelog text for use in Step 9.

Example output format:

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

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

Step 3: Confirm Version and Surfaces with User

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"