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

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 automates the entire bundling workflow. It creates a reproducible, validated ZIP archive from the current Git commit.

# 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 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 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:

• 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 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 — 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 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 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 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.

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