Where to Synchronize the Version Number in the Humanizer Project

The Humanizer project requires version number synchronization across three specific files—SKILL.md, README.md, and .claude-plugin/plugin.json—to ensure consistency between the skill metadata, documentation, and Claude Desktop plugin manifest.

The Humanizer repository (blader/humanizer) implements a strict versioning protocol that spans multiple configuration layers. To prevent release mismatches and guarantee that both AI agents and the Claude plugin load the correct skill version, maintainers must synchronize the version identifier across three distinct locations every time they publish a new release.

The Three Required Locations for Version Synchronization

According to the project maintainer guidelines documented in AGENTS.md【/cache/repos/github.com/blader/humanizer/main/AGENTS.md#L24-L26】, the version number must remain identical in the following three files.

1. SKILL.md – The Canonical Metadata Source

The canonical version resides in the YAML front-matter of SKILL.md under the metadata.version key. This serves as the primary reference for the skill's identity.

• Location: Lines 9-11 in SKILL.md【/cache/repos/github.com/blader/humanizer/main/SKILL.md#L9-L11】
• Format: YAML front-matter
• Example: metadata:\n version: "2.11.2"

---
name: humanizer
description: |
  Rewrite AI-sounding text so it reads naturally without changing what it says.
license: MIT
metadata:
  version: "2.11.2"
---

2. README.md – Public Version History

The first entry in the "Version history" section of README.md must match the canonical version string exactly. This ensures public documentation reflects the current release.

• Location: Lines 152-158 in README.md【/cache/repos/github.com/blader/humanizer/main/README.md#L152-L158】
• Requirement: The top-most bullet point in the version history list
• Example: - **2.11.2** - Removed the plugin symlink …

<!-- README.md – Version history -->

## Version history

<details>
<summary>Show release notes</summary>

- **2.11.2** - Removed the plugin symlink and separate Claude Desktop package. …

3. .claude-plugin/plugin.json – Plugin Manifest

The Claude Desktop plugin manifest requires its own version field to maintain compatibility with the Claude Code ecosystem. This JSON field must mirror the SKILL.md version string.

• Location: Lines 4-6 in .claude-plugin/plugin.json【/cache/repos/github.com/blader/humanizer/main/.claude-plugin/plugin.json#L4-L6】
• Format: Top-level JSON string value
• Example: "version": "2.11.2"

// .claude-plugin/plugin.json
{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "humanizer",
  "description": "Rewrite AI-sounding text so it reads naturally without changing what it says.",
  "version": "2.11.2",
  …
}

How the Humanizer Project Enforces Version Consistency

The repository provides automated safeguards to prevent version drift between these three files. The scripts/validate-package.py script runs validation checks to ensure the version strings remain synchronized across all required locations.

When preparing a release, maintainers should verify that:

• SKILL.md contains the new version in metadata.version
• README.md lists the identical version as the first entry in the changelog
• .claude-plugin/plugin.json reflects the same semantic version string

Failure to synchronize these files results in validation errors during the packaging process, blocking publication until the mismatch is resolved.

Summary

• Three files require synchronization: SKILL.md, README.md, and .claude-plugin/plugin.json
• Canonical source: The metadata.version field in SKILL.md front-matter serves as the primary reference
• Documentation sync: README.md must list the identical version as the first entry in its version history section
• Plugin compatibility: .claude-plugin/plugin.json requires a matching version field for Claude Desktop integration
• Validation: The scripts/validate-package.py script enforces consistency before release

Frequently Asked Questions

What happens if the version numbers are not synchronized in all three files?

If the version strings differ between SKILL.md, README.md, and .claude-plugin/plugin.json, the scripts/validate-package.py validation script will fail. This prevents the release from proceeding and ensures that agents load the correct skill version while avoiding mismatched documentation.

Which file contains the authoritative version number in the Humanizer project?

The authoritative version resides in SKILL.md within the metadata.version YAML front-matter field. This value serves as the canonical reference that must be mirrored in the README's version history and the Claude plugin manifest.

Why does the Claude plugin require a separate version field?

The .claude-plugin/plugin.json file functions as a standalone manifest for the Claude Desktop ecosystem. It requires its own top-level version field to inform the Claude Code client about the plugin's compatibility and update status, independent of the core skill logic defined in SKILL.md.

Is there a specific order for updating the version numbers?

While no strict sequence is enforced by the codebase, best practices suggest updating SKILL.md first to establish the new canonical version, then propagating that value to README.md (as the first changelog entry) and finally to .claude-plugin/plugin.json. Always run scripts/validate-package.py before committing to verify synchronization.

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