Plugin Version Synchronization Requirements Between SKILL.md and plugin.json Files

The watch skill requires identical version identifiers in three locations: skills/watch/SKILL.md frontmatter, .claude-plugin/plugin.json, and .codex-plugin/plugin.json.

Keeping plugin version numbers synchronized across multiple configuration files is essential for reliable distribution of AI agent skills. In the bradautomates/claude-video repository, the watch skill implementation demonstrates a strict three-file versioning requirement that prevents metadata mismatches across Claude Code, Codex, and other Agent-Skills hosts.

Where Version Synchronization Is Required

The repository's development guidelines, documented in AGENTS.md, mandate version consistency across three specific files. According to the source code rules: "Keep the version in sync across skills/watch/SKILL.md (frontmatter), .claude-plugin/plugin.json, and .codex-plugin/plugin.json when cutting a release."

Each file serves a distinct purpose in the skill distribution pipeline:

File	Purpose	Version Location
skills/watch/SKILL.md	Skill definition for agent systems	Frontmatter version: field
.claude-plugin/plugin.json	Claude Code plugin descriptor	Top-level "version" key
.codex-plugin/plugin.json	Codex/Agents plugin descriptor	Top-level "version" key

File-by-File Version Configuration

SKILL.md Frontmatter Version

The skill definition file uses YAML frontmatter to declare metadata. The version field on line 3 must be quoted as a string to ensure proper parsing:

---
name: watch
version: "0.2.0"
description: Watch for file changes and trigger actions
---

Claude Plugin Configuration

The .claude-plugin/plugin.json file contains the plugin manifest for Claude Code integration. The version string must exactly match the SKILL.md value:

{
  "name": "watch",
  "version": "0.2.0",
  "description": "Watch for file changes and trigger actions",
  "entry_point": "skills/watch"
}

Codex Plugin Configuration

The .codex-plugin/plugin.json file provides the equivalent manifest for OpenAI Codex and Agents SDK compatibility. This version must also remain identical:

{
  "name": "watch",
  "version": "0.2.0",
  "description": "Watch for file changes and trigger actions",
  "entry_point": "skills/watch"
}

Release Workflow for Version Updates

When preparing a new release tagged vX.Y.Z, you must edit all three files simultaneously. The synchronization process follows these steps:

1. Update skills/watch/SKILL.md — Modify the version: line in frontmatter
2. Update .claude-plugin/plugin.json — Modify the "version" field
3. Update .codex-plugin/plugin.json — Modify the "version" field
4. Commit with release tag — Ensure all changes are in a single commit or PR

Failing to synchronize these versions causes mismatched metadata that breaks skill installations and automated updates across supported platforms.

Version Format Requirements

Based on the repository implementation, version strings should follow semantic versioning with these constraints:

• Use quoted strings in JSON files to prevent numeric interpretation
• Include the leading v in git tags (v0.2.0) but exclude it from file contents ("0.2.0")
• Maintain identical precision across all three files (no 0.2.0 vs 0.2 mismatches)

Summary

• Three files require synchronized versions: skills/watch/SKILL.md, .claude-plugin/plugin.json, and .codex-plugin/plugin.json
• Version mismatch breaks platform compatibility for Claude Code and Codex installations
• Release workflow requires simultaneous updates to all three files when cutting a new version
• String formatting matters: Quote versions consistently to avoid parsing errors

Frequently Asked Questions

What happens if the versions don't match across files?

Mismatched versions cause metadata conflicts that prevent proper skill discovery and installation. Claude Code and Codex hosts rely on consistent version identifiers to determine available updates and resolve dependencies. Unsynchronized versions may result in failed installations or stale skill caching.

Do I need to include the "v" prefix in the version strings?

No. The file contents should use bare semantic versions like "0.2.0" without the v prefix. The leading v belongs only in git release tags (e.g., git tag v0.2.0), not in the configuration files themselves. This convention matches standard npm and package manager practices.

Can I automate version synchronization across these files?

While the repository currently requires manual editing, you could implement a release script that uses sed or a templating system to update all three files simultaneously. Any automation must preserve the distinct file formats: YAML frontmatter for SKILL.md, and JSON for both plugin.json files.

Are there other files that need version updates?

According to the AGENTS.md rules in the bradautomates/claude-video repository, only these three files require version synchronization. The README.md and other documentation may reference versions descriptively, but strict synchronization is only enforced across the SKILL.md and two plugin.json manifests.

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