How the Humanizer Package Validator Enforces Consistent Versioning Across Distribution Files

The humanizer package validator is a Python script that synchronizes version numbers across SKILL.md, README.md, and 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, 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.

README.md Version History Section

The validator scans 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 and extracts the top-level version key. This JSON value must mirror the strings found in both SKILL.md and 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, the validator constructs a Python set containing the three extracted version strings:

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:

# 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, README.md, and .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, 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 for YAML frontmatter version metadata, README.md for the first bullet under the Version History section, and .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 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.

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