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

The .skill bundle is a self-contained zip file built by executing 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 contract that defines the skill’s capabilities and the runtime scripts (such as 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 script explicitly aborts if uncommitted changes exist, ensuring the bundle reflects exactly what is committed at HEAD.

Run the following to verify your state:

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

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

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

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

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