# Where to Synchronize the Version Number in the Humanizer Project

> Discover where to synchronize the version number in the Humanizer project. Learn to update SKILL.md, README.md, and plugin.json for consistent skill metadata documentation and plugin manifests.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: development-process
- Published: 2026-09-06

---

**The Humanizer project requires version number synchronization across three specific files—[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md)【/cache/repos/github.com/blader/humanizer/main/SKILL.md#L9-L11】
- **Format**: YAML front-matter
- **Example**: `metadata:\n  version: "2.11.2"`

```yaml
---
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`](https://github.com/blader/humanizer/blob/main/README.md) must match the canonical version string exactly. This ensures public documentation reflects the current release.

- **Location**: Lines 152-158 in [`README.md`](https://github.com/blader/humanizer/blob/main/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 …`

```markdown
<!-- 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`](https://github.com/blader/humanizer/blob/main/.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"`

```json
// .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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains the new version in `metadata.version`
- [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) lists the identical version as the first entry in the changelog
- [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)
- **Canonical source**: The `metadata.version` field in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) front-matter serves as the primary reference
- **Documentation sync**: [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) must list the identical version as the first entry in its version history section
- **Plugin compatibility**: [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) requires a matching `version` field for Claude Desktop integration
- **Validation**: The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json), the [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) first to establish the new canonical version, then propagating that value to [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) (as the first changelog entry) and finally to [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json). Always run [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) before committing to verify synchronization.