# How to Build the .skill Bundle for Uploading to Claude.ai

> Learn how to build the .skill bundle for Claude.ai upload. Follow simple steps from the bradautomates/claude-video repository to create your validated bundle quickly.

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

---

**The .skill bundle is a self-contained zip file built by executing [`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, which automatically validates Claude.ai constraints and outputs `dist/watch.skill` ready for upload.**

To distribute your **watch** skill through the Claude.ai web interface, you must package the contract and runtime files into a conformant `.skill` archive. The `bradautomates/claude-video` repository provides a dedicated build script that enforces platform limits while producing a properly structured bundle.

## What the .skill Bundle Contains

The `.skill` file is a zip archive whose root directory is `watch/`. It includes everything under `skills/watch`, specifically the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract that defines the skill’s capabilities and the runtime scripts (such as [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)) that execute when the skill is invoked.

## Prerequisites Before Building

You must have a **clean Git working tree** before running the build script. The [`build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) script explicitly aborts if uncommitted changes exist, ensuring the bundle reflects exactly what is committed at `HEAD`.

Run the following to verify your state:

```bash
git status
git diff --quiet && git diff --cached --quiet || { echo "Commit or stash changes first"; exit 1; }

```

## How the build-skill.sh Script Works

The automation logic resides in [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) and executes five distinct phases:

### 1. Clean Working Tree Verification

Lines 14–17 check `git diff` and `git diff --cached`. If either detects changes, the script exits immediately to prevent packaging dirty code.

### 2. Output Directory Creation

Lines 19–21 ensure the `dist/` directory exists and sets the final output path to `dist/watch.skill`.

### 3. Subtree Archiving

Lines 21–22 invoke `git archive` to construct a zip file where the top-level directory is `watch/` and the contents mirror the `skills/watch/` subtree. This captures the contract and scripts without including Git metadata.

### 4. Claude.ai Constraint Validation

The script enforces two hard limits imposed by the platform:

- **File count ≤ 200**: Lines 23–30 count the zip entries. If the total exceeds 200, the build aborts and advises adding `export-ignore` entries to `.gitattributes` to exclude unnecessary files.
- **Single SKILL.md requirement**: Lines 32–36 verify the archive contains exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md). The script fails if zero or multiple instances are found.

### 5. Success Reporting

Lines 38–40 print the bundle path, total file count, and archive size, confirming that `dist/watch.skill` is ready for the Claude.ai upload workflow.

## Building the Bundle Step by Step

Execute these commands from the repository root:

```bash

# Verify no uncommitted changes

git diff --quiet && git diff --cached --quiet || { echo "Commit or stash first"; exit 1; }

# Build the bundle

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

```

The script outputs `dist/watch.skill`. You can verify its integrity manually:

```bash

# Check file count (must be ≤ 200)

unzip -l dist/watch.skill | wc -l

# Confirm exactly one SKILL.md exists

unzip -l dist/watch.skill | grep SKILL.md

```

## Troubleshooting Validation Failures

If the build fails due to the **200-file limit**, inspect your `skills/watch/` directory for extraneous assets (logs, cache files, or documentation). Add patterns to `.gitattributes` with the `export-ignore` attribute to exclude them from `git archive`:

```bash

# Example .gitattributes entry

tests/ export-ignore
*.log export-ignore

```

If the **SKILL.md validation** fails, ensure only one file with that exact name exists in the `skills/watch/` hierarchy and that it is not excluded by `.gitignore` or `.gitattributes`.

## Uploading to Claude.ai

Once `dist/watch.skill` is generated, navigate to **Settings → Capabilities → Skills** in the Claude.ai web interface. Drop the bundle into the upload panel to activate the skill.

## Summary

- The `.skill` bundle is a zip file created by [`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.
- The script enforces a **clean Git state** and validates the archive contains **≤ 200 files** and **exactly one SKILL.md**.
- Output is written to `dist/watch.skill` and uploaded via **Settings → Capabilities → Skills** on Claude.ai.
- Use `.gitattributes` with `export-ignore` to trim file counts that exceed platform limits.

## Frequently Asked Questions

### What is the maximum number of files allowed in a .skill bundle?

Claude.ai imposes a hard limit of **200 files** per bundle. The [`build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) script automatically counts entries and aborts if this threshold is exceeded, recommending you add `export-ignore` rules to `.gitattributes` to reduce the archive size.

### Can I build the .skill bundle with uncommitted changes?

No. The script explicitly checks `git diff` and `git diff --cached` at lines 14–17 and fails if any modifications are present. This ensures the generated bundle reflects committed code only, preventing runtime mismatches between your repository and the uploaded artifact.

### Where exactly do I upload the .skill file after building it?

Upload the generated `dist/watch.skill` file through the Claude.ai web interface at **Settings → Capabilities → Skills**. This panel accepts the bundle and activates the skill for use in conversations.

### Why does my build fail claiming there are multiple SKILL.md files?

The bundle must contain exactly one [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) at its root. The script checks for this at lines 32–36. If you have copies in subdirectories or if the file is missing entirely, validation fails. Ensure only one contract file exists under `skills/watch/` and that it is tracked by Git.