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

> Learn the plugin version synchronization requirements for SKILL.md and plugin.json files. Ensure identical version identifiers for seamless integration and functionality.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: best-practices
- Published: 2026-08-03

---

**The `watch` skill requires identical version identifiers in three locations: [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) frontmatter, [`.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).**

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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (frontmatter), [`.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) when cutting a release."*

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

| File | Purpose | Version Location |
|------|---------|------------------|
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) | Skill definition for agent systems | Frontmatter `version:` field |
| [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) | Claude Code plugin descriptor | Top-level `"version"` key |
| [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.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:

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

```

### Claude Plugin Configuration

The [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) file contains the plugin manifest for Claude Code integration. The version string must exactly match the SKILL.md value:

```json
{
  "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`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) file provides the equivalent manifest for OpenAI Codex and Agents SDK compatibility. This version must also remain identical:

```json
{
  "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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** — Modify the `version:` line in frontmatter
2. **Update [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json)** — Modify the `"version"` field
3. **Update [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.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`](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)
- **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`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) rules in the `bradautomates/claude-video` repository, only these three files require version synchronization. The [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) and other documentation may reference versions descriptively, but strict synchronization is only enforced across the SKILL.md and two plugin.json manifests.