# How to Build the watch.skill Bundle for Uploading to Claude AI

> Learn how to build the watch.skill bundle for Claude AI. This guide uses the build script to archive and validate your skill for upload, ensuring it meets all requirements.

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

---

**The `watch.skill` bundle is built using the [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) helper script, which validates the repository state, archives the skill subtree into a ZIP file, and verifies it meets Claude AI's upload constraints.**

The `bradautomates/claude-video` repository provides a custom skill for video processing that requires bundling before deployment. To build the `watch.skill` bundle for uploading to Claude AI, you run a single bash script that handles packaging, validation, and compliance checks automatically.

## Prerequisites: Clean Git State

The build script enforces strict version control hygiene to ensure reproducible bundles. Before running the script, your working directory must be clean.

In [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh), the script checks for uncommitted changes using `git diff --quiet` and aborts immediately if the repository is dirty:

```bash
if ! git diff --quiet; then
  echo "error: working tree is dirty; commit or stash before building"
  exit 1
fi

```

This validation guarantees that every generated `watch.skill` bundle corresponds to an exact Git commit, eliminating "works on my machine" deployment issues.

## Running the Build Script

To generate the bundle, execute the build script from any directory within the repository:

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

```

The script performs four sequential operations:

1. **Validates Git state** - Confirms no uncommitted changes exist before proceeding
2. **Creates the output directory** - Ensures `dist/` exists to receive the output
3. **Archives the skill** - Uses `git archive` to package the `skills/watch` subtree into `dist/watch.skill`
4. **Validates constraints** - Enforces Claude AI's upload limits and requirements

### Archive Creation Process

The script leverages `git archive` with specific flags to create a clean ZIP distribution. According to the source code in [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh), the command applies the prefix `watch/` so the resulting ZIP contains a single top-level directory. This structure places [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and the entire `scripts/` runtime in the correct location for Claude AI ingestion.

### Built-in Validation Checks

Before declaring success, the script validates the bundle against Claude AI's hard constraints:

- **File count limit**: The script counts entries in the ZIP and aborts if there are more than 200 files, which matches Claude AI's maximum file limit
- **SKILL.md requirement**: The script verifies exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file exists in the bundle; otherwise, it fails with an error

These checks prevent upload failures that would otherwise only surface in the Claude AI web interface.

## Understanding the Output

Upon successful completion, the script reports the bundle statistics and upload instructions:

```

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

```

The generated `dist/watch.skill` file is a ZIP archive containing the canonical [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract and all runtime scripts from the `skills/watch` directory. As noted in the repository's [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md), this file is ready for immediate upload through the Claude AI skill interface.

## Troubleshooting Common Issues

### Dirty Working Tree Error

If you encounter `error: working tree is dirty; commit or stash before building`, stage your changes using `git add` and commit them before running the build script. The script intentionally prevents building from modified working directories to ensure bundle integrity.

### File Count Exceeded

If validation fails with a file count error, remove unnecessary assets from the `skills/watch` directory, commit the deletions, and rebuild. The 200-file limit is enforced by Claude AI itself, not merely by the build script.

## Summary

- Execute `bash skills/watch/scripts/build-skill.sh` to generate the bundle in a single step
- The script requires a clean Git working tree and uses `git diff --quiet` to verify repository state
- Output is written to `dist/watch.skill` as a ZIP archive with the `watch/` directory prefix
- Validation enforces Claude AI's 200-file limit and requires exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file
- Upload the generated file through the Claude AI skill UI as instructed in the [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md)

## Frequently Asked Questions

### Where is the build script located?

The build script is located 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. This self-contained script handles the entire bundling process without modifying your repository.

### Why does the build require a clean Git state?

The script uses `git diff --quiet` to verify no uncommitted changes exist. This ensures the `watch.skill` bundle reflects an exact commit hash, making deployments traceable and reproducible across different environments.

### What validation does the script perform before creating the bundle?

The script validates two critical constraints for Claude AI compatibility: it counts files in the ZIP and aborts if exceeding 200 (Claude AI's hard limit), and it verifies exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file exists in the bundle structure.

### Can I build the bundle manually without using the script?

While possible, manual creation risks violating Claude AI's upload constraints. The script in [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) handles the specific `git archive` flags, directory prefixing, and validation checks required for successful upload, as documented in the repository's [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md).