What Does the release-skill.yml Workflow Do? Automating Tag-Driven Skill Releases

The release-skill.yml workflow is a GitHub Actions automation that manages independent, semantic-versioned releases for individual skills in the Garden-Skills repository whenever a tag matching the *-v* pattern is pushed.

The release-skill.yml workflow resides in the ConardLi/garden-skills repository and orchestrates the entire lifecycle of a skill release—from parsing Git tags to publishing GitHub releases and updating documentation. This automation ensures that each skill can be versioned and distributed independently without manual intervention.

How the release-skill.yml Workflow Works

The workflow executes a seven-step pipeline defined in .github/workflows/release-skill.yml. Each stage validates inputs, builds artifacts, and synchronizes project metadata.

Trigger Conditions

The workflow initiates on tag pushes matching the pattern *-v* (lines 22‑30). For example, pushing web-design-engineer-v1.2.0 triggers the automation for that specific skill. The workflow uses the on.push.tags filter to ensure it only responds to properly formatted version tags.

Tag Parsing and Validation

Upon execution, the workflow extracts the skill name and semantic version using a Bash regex (lines 48‑60). The tag must follow the strict format <skill>-v<semver>; otherwise, the job aborts immediately to prevent invalid releases.

Subsequent validation ensures the skill exists in the skills/<skill>/ directory and contains a manifest.json file (lines 63‑72). This guarantees that only documented, properly structured skills can be released.

Building and Packaging

The workflow executes npm run pack (lines 74‑80), which invokes scripts/release/pack-skill.mjs. This script creates a ZIP archive of the skill directory and generates a SHA‑256 checksum, placing both artifacts in dist/release/<skill>-<version>.zip and dist/release/<skill>-<version>.zip.sha256.

Release Notes Generation

Between lines 81‑124, the workflow generates a markdown changelog by:

• Identifying the previous tag for the same skill to determine the commit range
• Listing all commits affecting the skill since the previous release
• Creating an "Initial release" message for first-time versions
• Adding an "Install" section with CLI commands and direct-download instructions
• Embedding the SHA‑256 hash of the ZIP file for verification

The resulting release-notes.md serves as the release description.

GitHub Release Creation

Using the gh CLI (lines 125‑136), the workflow creates a GitHub Release named after the tag. It attaches the ZIP archive and checksum file as release assets and publishes the generated markdown as the release body. This provides users with verified, downloadable artifacts alongside installation documentation.

Documentation Synchronization

The final stage checks out the repository's default branch—necessary because tag checkouts create detached HEAD states—and runs npm run readme:sync (lines 138‑162). This command invokes scripts/release/readme-sync.mjs to update inline "Download v<version> .zip" links in README.md, README.zh-CN.md, and README.ja-JP.md. If any documentation changes occur, the workflow automatically commits and pushes them to the default branch.

Triggering a Skill Release

To release a skill, maintainers push a properly formatted tag:

# Release version 1.2.0 of the web-design-engineer skill

git tag web-design-engineer-v1.2.0
git push origin web-design-engineer-v1.2.0

This push triggers the release-skill.yml workflow, which validates that the version in skills/web-design-engineer/manifest.json matches the tag, creates the distribution archive in dist/release/, and publishes the GitHub Release.

Installing Released Skills

Users can install released skills using the Skills CLI or direct download:

# Install via CLI

npx skills add ConardLi/garden-skills/tree/web-design-engineer-v1.2.0/skills/web-design-engineer

# Or download and extract manually

curl -fsSL -o web-design-engineer.zip \
  https://github.com/ConardLi/garden-skills/releases/download/web-design-engineer-v1.2.0/web-design-engineer-1.2.0.zip
unzip web-design-engineer.zip -d .claude/skills/

The workflow ensures the SHA‑256 checksum is available for integrity verification.

Key Files in the Release Pipeline

• .github/workflows/release-skill.yml – Core automation logic handling tag parsing, validation, packaging, release creation, and README synchronization.
• scripts/release/pack-skill.mjs – Implements the npm run pack command that bundles skills into ZIP archives with cryptographic checksums.
• scripts/release/readme-sync.mjs – Updates localized README files with current download links when invoked via npm run readme:sync.
• skills/<skill>/manifest.json – Defines skill metadata including the version field that must align with the Git tag.

Summary

• The release-skill.yml workflow enables independent, tag-driven releases for each skill in the Garden-Skills repository.
• It validates tags against the <skill>-v<semver> pattern and verifies the existence of skills/<skill>/manifest.json before processing.
• The workflow generates ZIP archives with SHA‑256 checksums, creates detailed release notes with installation instructions, and publishes GitHub Releases automatically.
• Documentation synchronization ensures README.md files always contain current download links through npm run readme:sync.
• All automation triggers on Git tag pushes, requiring no manual intervention for standard releases.

Frequently Asked Questions

What tag format triggers the release-skill.yml workflow?

The workflow triggers exclusively on tags matching the *-v* pattern, specifically requiring the format <skill>-v<semver> such as web-design-engineer-v1.2.0. If the tag does not conform to this structure, the workflow aborts during the parsing phase (lines 48‑60).

How does the workflow ensure the release version matches the skill's manifest?

During the validation stage (lines 63‑72), the workflow verifies that the skill directory exists and checks its manifest.json file. While the workflow itself validates the directory structure, the npm run pack command ensures the version specified in the tag aligns with the version field in manifest.json before creating the distribution archive.

What files are generated during a skill release?

The workflow produces three primary artifacts in dist/release/: the skill ZIP archive (e.g., web-design-engineer-1.2.0.zip), its SHA‑256 checksum file (.zip.sha256), and a markdown file (release-notes.md) containing the changelog and installation instructions. These files are attached to the GitHub Release created in steps 125‑136.

Can the workflow update documentation automatically?

Yes. The final job stage (lines 138‑162) checks out the default branch and executes npm run readme:sync, which invokes scripts/release/readme-sync.mjs to update download links in all localized README files. If changes are detected, the workflow commits and pushes them automatically, ensuring documentation remains synchronized with the latest release.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}