# How Claude Video Manages Version Synchronization Across Releases

> Discover how Claude Video masterfully manages version synchronization across releases. Learn how SKILL.md acts as the single source of truth, automatically updating plugin files for seamless integration.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-28

---

**Claude Video uses [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) as the single source of truth for version numbers, automatically syncing the value to [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) via the [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) build script during the release process.**

Claude Video is distributed as a self-contained Agent Skill requiring consistent version metadata across multiple platforms. The **version synchronization** strategy ensures that maintainers update only one file—the skill manifest—while automation handles the propagation to plugin manifests for Claude Code and Codex/Agents compatibility.

## The Single Source of Truth

The master version declaration resides in the front matter of [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md). This file contains the line `version: "0.2.0"` at line 3, which serves as the definitive reference for the entire release. By centralizing the version string here, the repository eliminates the risk of drift between different packaging formats.

When preparing a release, maintainers edit only this front-matter field. All other version references throughout the repository are derived automatically from this single location during the build process.

## Automated Propagation via Build Script

The [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) script enforces **version synchronization** by extracting the version string from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and injecting it into both plugin descriptor files. This bash script parses the YAML front matter, then writes the extracted value to the `"version"` keys in the JSON manifests.

Because the build script regenerates these files automatically, the version flows in one direction:

```

SKILL.md ──► build-skill.sh ► .claude-plugin/plugin.json
                               ► .codex-plugin/plugin.json

```

This automation prevents human error, ensuring that [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) never contain stale version numbers.

## Plugin Manifest Targets

The build script updates two distinct plugin metadata files to support different host environments.

### Claude-Code Plugin (.claude-plugin/plugin.json)

The file [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) contains the plugin metadata required for Claude Code installations. The build script updates the `"version": "0.2.0"` field at line 3 to match the skill manifest. This ensures compatibility when users install the skill via the Claude Code plugin system.

### Codex/Agents Plugin (.codex-plugin/plugin.json)

Similarly, [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) at line 3 receives the synchronized version number. This file enables the skill to function on non-Claude hosts that support the Codex/Agents protocol. Both JSON files remain identical in version content, though they may differ in other configuration parameters.

## Release Workflow and Verification

The release process documented in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) (line 242) and [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) (line 48) explicitly instructs maintainers to "Keep the version in sync across [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json), and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json)". While the build script handles the JSON files automatically, these documentation reminders ensure the source file is bumped before tagging.

The workflow proceeds as follows:

1. Update the version in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) using `sed` or manual editing
2. Run the build script to regenerate the distribution bundle
3. Verify the JSON files contain the new version
4. Commit, tag, and push to trigger CI/CD

```bash

# Bump the version in the single source of truth

sed -i 's/^version: .*/version: "0.3.0"/' skills/watch/SKILL.md

# Build the distribution bundle – the script copies the new version

bash skills/watch/scripts/build-skill.sh   # → dist/watch.skill

# Verify that the JSON files were updated automatically

grep '"version":' .claude-plugin/plugin.json
grep '"version":' .codex-plugin/plugin.json

```

```bash

# Release workflow (as described in README)

git commit -am "Release v0.3.0"
git tag v0.3.0
git push && git push --tags

# CI builds dist/watch.skill and attaches it to the GitHub release

```

When the CI pipeline runs, it executes the build script, producing a consistent `dist/watch.skill` artifact that contains correctly versioned metadata for all supported platforms.

## Summary

- **Single source of truth**: The version declared in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) front matter drives all other version declarations.
- **Automated synchronization**: The [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) script extracts the version from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and writes it to both [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json).
- **One-way data flow**: Changes propagate from the skill manifest to plugin manifests; JSON files are never edited manually.
- **CI/CD integration**: The release workflow documented in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) and [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) ensures proper versioning before Git tags are pushed.

## Frequently Asked Questions

### What file serves as the single source of truth for Claude Video versions?

The [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) file serves as the single source of truth. Its YAML front matter contains the `version:` field at line 3 that drives all other version declarations in the repository. According to the source code analysis, this file is the master record that the build script references when generating distribution bundles.

### How does the build script extract and propagate the version number?

The [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) script parses the front matter of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) to extract the version string, then writes that value to the `"version"` keys in both [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json). This occurs during the bundle creation process before the `dist/watch.skill` archive is generated, ensuring both plugin manifests remain identical to the skill manifest.

### Do I need to manually update the plugin.json files when releasing?

No. Manual updates to the JSON files are unnecessary and discouraged because the build script automatically regenerates these files with the correct version extracted from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md). The release instructions in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) (line 242) and [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) (line 48) remind maintainers to update only the skill manifest, trusting the automation to handle synchronization.

### Where are the release instructions documented for maintainers?

Release instructions appear in two locations: [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) at line 242 and [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) at line 48. Both documents explicitly instruct maintainers to keep versions synchronized across the three metadata files and describe the Git tagging workflow that triggers the automated build process in CI/CD.