How Claude Video Manages Version Synchronization Across Releases

Claude Video uses skills/watch/SKILL.md as the single source of truth for version numbers, automatically syncing the value to .claude-plugin/plugin.json and .codex-plugin/plugin.json via the 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. 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 script enforces version synchronization by extracting the version string from 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 and .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 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 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 (line 242) and AGENTS.md (line 48) explicitly instructs maintainers to "Keep the version in sync across skills/watch/SKILL.md, .claude-plugin/plugin.json, and .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 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

# 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

# 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 front matter drives all other version declarations.
• Automated synchronization: The skills/watch/scripts/build-skill.sh script extracts the version from SKILL.md and writes it to both .claude-plugin/plugin.json and .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 and 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 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 script parses the front matter of SKILL.md to extract the version string, then writes that value to the "version" keys in both .claude-plugin/plugin.json and .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. The release instructions in README.md (line 242) and 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 at line 242 and 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.

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