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

The watch.skill bundle is built using the 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, the script checks for uncommitted changes using git diff --quiet and aborts immediately if the repository is dirty:

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 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, the command applies the prefix watch/ so the resulting ZIP contains a single top-level directory. This structure places 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 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 contract and all runtime scripts from the skills/watch directory. As noted in the repository's 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 file
• Upload the generated file through the Claude AI skill UI as instructed in the README.md

Frequently Asked Questions

Where is the build script located?

The build script is located at 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 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 handles the specific git archive flags, directory prefixing, and validation checks required for successful upload, as documented in the repository's README.md.

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