# How the Claude-Video Release Workflow Builds the watch.skill Bundle

> Learn how the claude-video release workflow builds the watch.skill bundle using a local script for validation and archiving, followed by a GitHub Actions pipeline for publishing artifacts on version tags.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: architecture
- Published: 2026-08-13

---

**The claude-video release workflow constructs the `watch.skill` bundle through a tightly coupled two-stage process: a local shell script validates repository state and archives the skill directory, then a GitHub Actions pipeline triggers on version tags to publish the artifact.**

The claude-video repository automates the packaging of its Claude AI skill through a rigorous build and release system. Understanding how the claude-video release workflow assembles the `watch.skill` bundle reveals a validation-heavy pattern that ensures every release complies with platform constraints and maintains bit-for-bit reproducibility.

## Local Build Script: [`build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh)

The foundation of the release process resides in [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) (lines 1-40). This script enforces strict prerequisites before generating the distributable artifact at `dist/watch.skill`.

### Enforcing Repository Cleanliness

The script aborts immediately if uncommitted changes exist. It verifies repository cleanliness using:

```bash
git diff --quiet
git diff --cached --quiet

```

If either command detects modifications, the build fails. This guarantees that the resulting bundle reflects exactly the committed state of the repository, excluding any local work-in-progress.

### Archiving the Skill Directory

Once validation passes, the script uses `git archive` to create a zip file containing the entire `skills/watch` directory. The command preserves the directory structure under a top-level `watch/` prefix:

```bash
git archive --format=zip -o dist/watch.skill HEAD:skills/watch

```

This archive includes [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (the canonical skill contract) and the `scripts/` runtime directory containing [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

### Validating Claude AI Constraints

After archiving, the script performs two critical validation checks against Claude AI upload requirements:

- **File count limit**: It counts entries using `unzip -l` and validates against the 200-file cap, failing early if the limit is exceeded.
- **Contract verification**: It confirms exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) exists using `grep -c "SKILL.md"`, ensuring the bundle contains the required entry point.

Upon success, the script reports the artifact path, total file count, and bundle size.

## GitHub Actions Release Pipeline

The [`.github/workflows/release.yml`](https://github.com/bradautomates/claude-video/blob/main/.github/workflows/release.yml) file (lines 1-32) automates execution of the build script and handles publication to GitHub Releases.

### Tag-Based Workflow Triggers

The workflow initiates on any push of a tag matching the `v*` pattern (for example, `v1.2.3`):

```yaml
on:
  push:
    tags:
      - 'v*'

```

### Artifact Generation and Publishing

The pipeline performs three sequential operations:

1. **Checkout**: `actions/checkout@v4` fetches the full repository history so the build script can access git metadata.
2. **Build execution**: It runs `bash skills/watch/scripts/build-skill.sh`, followed by a sanity check (`test -f dist/watch.skill`) to verify artifact creation.
3. **Release creation**: The `softprops/action-gh-release@v2` action generates a GitHub release and attaches `dist/watch.skill` as the sole asset, automatically producing release notes.

## Publishing a New Release

In practice, maintainers publish versions by ensuring repository cleanliness and pushing semantic version tags:

```bash

# Verify clean working tree

git status   # should show "nothing to commit, working tree clean"

# Create and push version tag

git tag v1.0.0
git push origin v1.0.0

```

When the tag reaches GitHub, the workflow runs automatically, producing `dist/watch.skill` and publishing a release containing the bundled skill ready for upload to claude.ai.

## Summary

- The **local build script** ([`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh)) enforces git cleanliness using `git diff --quiet`, archives the skill via `git archive`, and validates the 200-file limit and [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) presence.
- The **GitHub Actions workflow** ([`.github/workflows/release.yml`](https://github.com/bradautomates/claude-video/blob/main/.github/workflows/release.yml)) triggers on `v*` tags, executes the build script, and publishes releases using `softprops/action-gh-release@v2`.
- The bundle includes [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (the contract) and [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (the runtime).
- Strict validation ensures every `watch.skill` artifact is reproducible and compliant with Claude AI constraints.

## Frequently Asked Questions

### How does the build script ensure reproducible bundles?

The script enforces a clean git working tree using `git diff --quiet` and `git diff --cached --quiet` checks before archiving. By using `git archive` to package `HEAD:skills/watch`, it guarantees the bundle contains exactly the committed state without local uncommitted modifications.

### What validation checks does the watch.skill bundle undergo?

The script validates two Claude AI platform constraints: it checks the total file count against the 200-file limit using `unzip -l`, and verifies exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) exists using `grep -c`. These checks fail the build immediately if violated, preventing invalid uploads.

### How do I trigger the release workflow manually?

Push a semantic version tag matching the `v*` pattern (for example, `v1.2.3`) to the remote repository. The workflow defined in [`.github/workflows/release.yml`](https://github.com/bradautomates/claude-video/blob/main/.github/workflows/release.yml) triggers automatically on tag push, executing the build script and creating a GitHub release with the `watch.skill` artifact attached.

### What files are included in the final watch.skill bundle?

The bundle contains the entire `skills/watch` directory archived under a `watch/` prefix. This includes [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) (the required skill contract) and the `scripts/` subdirectory containing [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and supporting runtime files.