# How Version History Is Managed in Humanizer: A Complete Guide

> Learn how Humanizer manages version history effectively. Discover its approach to release notes, version tracking, and validation in this comprehensive guide.

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

---

**Humanizer manages version history by storing the current release in the `metadata.version` field of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and maintaining chronological release notes within a `<details>` block in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), validated for consistency using [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/README.md), using the identical version label and a concise description of changes.

3. **Run the validation script** ([`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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**

```text
/humanizer --info

```

*Example output:*

```

Humanizer version: 3.0.0

```

**Retrieving the Full Changelog**

```text
/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**

```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`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) configuration ensures agents load [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md), add a corresponding entry to the `<details>` block in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and run [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) file points directly to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), making the version immediately accessible to the runtime environment.