# How the Humanizer Package Validator Enforces Consistent Versioning Across Distribution Files

> Learn how the humanizer package validator enforces consistent versioning across distribution files like SKILL.md README.md and plugin.json ensuring accuracy before publication.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: how-to-guide
- Published: 2026-09-11

---

**The humanizer package validator is a Python script that synchronizes version numbers across [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) by extracting values from each file and enforcing that all three match exactly before allowing publication.**

The `blader/humanizer` repository maintains version synchronization across multiple distribution formats using a dedicated validation script. This humanizer package validator prevents accidental version drift between the skill definition, documentation, and Claude plugin metadata by implementing strict equality checks at build time.

## Where the Humanizer Package Validator Sources Version Metadata

The validation script inspects three specific locations to extract the current package version:

### SKILL.md YAML Frontmatter

In [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), the validator parses the YAML metadata block to locate the `version` field. The script expects a numeric version string enclosed in quotes, such as `"3.0.0"`, positioned at line 10 of the file. If the `metadata.version` key is absent, the validator raises an error at line 45 of [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py).

### README.md Version History Section

The validator scans [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) for the first bullet point beneath the "Version History" section, typically found at line 50. This entry must follow the format `- **3.0.0**` to be recognized as the canonical version identifier. Missing entries trigger validation failures at line 49 of the script.

### plugin.json Manifest File

For Claude plugin compatibility, the validator loads [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) and extracts the top-level `version` key. This JSON value must mirror the strings found in both [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and [`README.md`](https://github.com/blader/humanizer/blob/main/README.md). The script aborts with a parsing error at lines 24-27 if the JSON structure is malformed.

## How the Humanizer Package Validator Enforces Version Equality

At the core of [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), the validator constructs a Python set containing the three extracted version strings:

```python
package_versions = {
    skill_version, 
    readme_version, 
    str(PLUGIN.get("version", ""))
}

```

The script then verifies that this set contains exactly one element. This mathematical approach ensures that `skill_version`, `readme_version`, and the plugin JSON version are identical. Lines 54-58 of the validator implement this check, raising a `SystemExit` with the message `Use one package version in all files` followed by the mismatched values if the set length exceeds one.

## Fail-Fast Error Handling in the Humanizer Package Validator

The humanizer package validator implements aggressive error detection to catch malformed inputs before they reach distribution:

- **Missing SKILL.md metadata**: If the YAML frontmatter lacks a `version` field, the script fails at line 45 with a descriptive error.
- **Absent README version**: When the Version History section contains no recognizable version bullet, validation fails at line 49.
- **Invalid JSON structure**: The plugin manifest must parse as valid JSON; otherwise, the script terminates at lines 24-27 before version extraction occurs.

## Running the Humanizer Package Validator Locally

Execute the validation script from the repository root to verify version synchronization before committing:

```bash

# Run the validator locally (requires Python 3)

python3 scripts/validate-package.py

# → prints “Humanizer package v3.0.0 is valid” if all versions match

```

When versions diverge, the script exits immediately with output similar to:

```

SystemExit: Use one package version in all files: ['3.0.0', '3.1.0']

```

## Summary

- The humanizer package validator maintains version consistency across three distribution 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).
- The script extracts version strings using file-specific parsers: YAML frontmatter parsing, markdown bullet extraction, and JSON key access.
- Validation occurs through set comparison logic at lines 54-58 of [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), enforcing that exactly one unique version exists across all files.
- Fail-fast error handling prevents publication when any file contains missing or malformed version data.

## Frequently Asked Questions

### What files does the humanizer package validator check?

The validator inspects three files: [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) for YAML frontmatter version metadata, [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) for the first bullet under the Version History section, and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) for the top-level JSON version key. All three locations must contain identical version strings.

### What happens if the versions don't match?

When version strings differ across files, the humanizer package validator raises a `SystemExit` error displaying the conflicting values, such as `Use one package version in all files: ['3.0.0', '3.1.0']`. This prevents the package from building or publishing with inconsistent metadata.

### Where is the validation script located?

The core validation logic resides in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) at the repository root. This Python script contains the extraction and comparison logic that enforces version synchronization across the humanizer package distribution files.

### How does the validator handle missing version data?

The script implements fail-fast validation: it raises specific errors at lines 45, 49, and 24-27 for missing YAML metadata, absent README entries, and malformed JSON respectively. This ensures incomplete version information never reaches production builds.