How Version History Is Managed in Humanizer: A Complete Guide

Humanizer manages version history by storing the current release in the metadata.version field of SKILL.md and maintaining chronological release notes within a <details> block in README.md, validated for consistency using scripts/validate-package.py.

The blader/humanizer repository implements a lightweight, Markdown-native approach to version history that eliminates complex build pipelines. Instead of traditional package manifests, this open-source skill tracks releases through structured front-matter metadata while documenting changes directly in the repository's primary documentation files.

How Humanizer Stores the Current Version in SKILL.md

In blader/humanizer, the single source of truth for the release number resides in SKILL.md. At line 10, the file declares the current version within the front-matter metadata: metadata.version: "3.0.0". Because the skill is implemented as pure Markdown, agents read this version directly from the file header without requiring compilation steps or external package managers.

Tracking Changes in the README.md Release Notes

While SKILL.md contains the machine-readable version identifier, README.md holds the human-readable version history. The maintainers document each release inside a collapsible <details> block, typically located at lines 66–73. Each entry records the version number alongside a summary of structural changes—for example, the 3.0.0 entry describes the consolidation of patterns around a unified account of AI text characteristics.

The Three-Step Version Release Workflow

Updating the version history requires a manual synchronization process that keeps metadata and documentation aligned:

1. Bump the version in SKILL.md by updating the metadata.version field to the new release number (e.g., "3.0.0").

2. Add a changelog entry at the top of the <details> block in README.md, using the identical version label and a concise description of changes.

3. Run the validation script (scripts/validate-package.py) to verify that the version field matches the most recent release notes header.

Validating Version Consistency with validate-package.py

The repository includes scripts/validate-package.py specifically to prevent version drift between the metadata and documentation. This script cross-references the metadata.version value in SKILL.md against the latest entry in the README's changelog, failing validation if the two do not match. This check substitutes for traditional package integrity verification in this Markdown-native ecosystem.

Accessing Version History Programmatically

Because version data resides in plain text Markdown, developers can query it through multiple interfaces without parsing binary files.

Querying the Current Version via CLI

/humanizer --info

Example output:

Humanizer version: 3.0.0

Retrieving the Full Changelog

/humanizer:humanizer --changelog

Example output:

- 3.0.0 – Rebuilt the skill around one account of why AI text sounds the way it does…
- 2.11.3 – Grouped patterns 26‑35 under “More style patterns”…

Reading Version Data with Python

import re
import pathlib

def get_humanizer_version():
    text = pathlib.Path("SKILL.md").read_text()
    match = re.search(r'metadata:\s*\n\s*version:\s*"([^"]+)"', text)
    return match.group(1) if match else "unknown"

print("Current Humanizer version:", get_humanizer_version())

Summary

• SKILL.md stores the canonical version in metadata.version at line 10, currently set to "3.0.0".
• README.md contains human-readable release notes inside a <details> block at lines 66–73.
• scripts/validate-package.py enforces consistency between the metadata field and changelog entries.
• The .claude-plugin/plugin.json configuration ensures agents load SKILL.md directly, making version data immediately accessible without build steps.

Frequently Asked Questions

Where is the current version number defined in Humanizer?

The current version is defined in the metadata.version field of SKILL.md at line 10. This front-matter field is currently set to "3.0.0" and serves as the authoritative source for runtime agents querying the skill's release.

How do maintainers update the version history when releasing a new version?

Maintainers follow a three-step manual process: update metadata.version in SKILL.md, add a corresponding entry to the <details> block in README.md, and run scripts/validate-package.py to verify the versions match.

Can I check the Humanizer version without opening the Markdown files?

Yes. If running in a compatible agent environment like Claude Desktop, you can execute /humanizer --info to display the current version or /humanizer:humanizer --changelog to view the full release history.

Why does Humanizer store version data in Markdown instead of a JSON package file?

As a pure Markdown skill, Humanizer exposes version information through front-matter metadata so agents can load it without additional build steps. The .claude-plugin/plugin.json file points directly to SKILL.md, making the version immediately accessible to the runtime environment.

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