# How to Build the `watch.skill` Bundle for Claude AI Web Upload

> Easily build the watch.skill bundle for Claude AI web upload. Run the build script from the repository root to create a validated ZIP file ready for Claude.ai.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Run `bash skills/watch/scripts/build-skill.sh` from the repository root to generate `dist/watch.skill`, a validated ZIP file ready for upload to claude.ai.**

The `bradautomates/claude-video` repository includes a complete `watch` skill that can be bundled and uploaded to Claude AI as a custom skill. The build process is handled by a single shell script that ensures your bundle meets Claude AI's requirements before you upload it.

## Using the Build Script

The helper script at [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) automates the entire bundling workflow. It creates a reproducible, validated ZIP archive from the current Git commit.

```bash

# From the root of the cloned repository

bash skills/watch/scripts/build-skill.sh

```

Typical output shows file count and size:

```

built dist/watch.skill (140 files, 1.2M)
upload via the claude.ai skill UI

```

## What the Build Script Does

The script performs five distinct operations:

1. **Validates Git state** — Aborts with error if uncommitted changes exist (`git diff --quiet`). This guarantees the bundle reflects an exact commit.
2. **Creates output directory** — Ensures `dist/` exists before writing.
3. **Archives the skill subtree** — Uses `git archive` to zip `skills/watch` with prefix `watch/`, producing `dist/watch.skill`. The ZIP contains [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and the `scripts/` runtime under a single top-level directory.
4. **Enforces Claude AI limits** — Fails if the bundle exceeds 200 files (Claude AI's hard limit) or contains zero/multiple [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) files.
5. **Reports results** — Prints file count, size, and upload instructions.

## Validation Checks Explained

The script implements two critical safeguards from lines 23–36 of [`build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh):

- **File count limit**: Extracts and counts ZIP contents, aborting if > 200 files
- **SKILL.md verification**: Unzips to a temp directory and confirms exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) exists

These checks prevent rejected uploads from malformed bundles.

## Handling Build Errors

If your working tree has uncommitted changes, the script exits immediately:

```

error: working tree is dirty; commit or stash before building

```

Commit or stash changes, then rerun the build command.

## Bundle Contents

The generated `dist/watch.skill` is a standard ZIP containing:

- [`watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/watch/SKILL.md) — The skill's canonical contract defining `/watch` commands
- `watch/scripts/` — Runtime scripts implementing skill functionality

Because `git archive` reads from the repository, the bundle is reproducible and traceable to a specific commit.

## Summary

- Run `bash skills/watch/scripts/build-skill.sh` to create `dist/watch.skill`
- The script validates Git cleanliness, archives the `skills/watch` subtree, and enforces Claude AI limits
- Upload the resulting ZIP through the claude.ai skill UI
- Bundle must contain exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and fewer than 200 files

## Frequently Asked Questions

### Where is the build script located?

The build script is at [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) in the `bradautomates/claude-video` repository. Run it from any directory inside the cloned repository using the relative path.

### Why does the build fail with "working tree is dirty"?

The script requires a clean Git state to ensure reproducible bundles. Commit or stash your changes, then rebuild. This prevents accidental inclusion of uncommitted experimental code in production skill bundles.

### What are Claude AI's skill bundle limits?

Claude AI enforces a 200-file maximum per skill bundle. The build script validates this automatically. Additionally, exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file must be present—multiple or missing files cause build failure.

### Can I modify the bundle after building?

Manual modifications break traceability. The script design intentionally prevents this by reading directly from Git. Make changes in the repository, commit them, and rebuild to generate a valid, trackable bundle.