# How the Humanizer Script Validates Package Files: 11-Step Verification Process

> Discover how the Humanizer script validates package files through 11 checks. Ensure YAML integrity and version consistency across key files like SKILL.md and README.md.

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

---

**The Humanizer script validates package files by running 11 deterministic checks in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) to ensure YAML metadata integrity, version consistency across [`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), pattern numbering sequencing, and plain-language rule compliance.**

The `blader/humanizer` repository maintains packaging integrity through a self-contained Python validator. Understanding how the Humanizer script validates package files reveals a comprehensive quality assurance system that operates without external dependencies, ensuring all documentation and metadata remain perfectly synchronized before deployment.

## Core Validation Architecture

The validation logic resides entirely in **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)**, a standalone script that loads and inspects four critical repository files: [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json). Using only Python standard library modules like `pathlib` and `re`, the script performs deterministic checks that abort with descriptive `SystemExit` errors immediately upon detecting inconsistencies.

### File Loading Mechanism

The script begins by establishing the repository root and loading file contents into memory. It uses `Path.read_text()` to ingest the raw contents of each target file, storing them as string variables for subsequent regex operations and content validation.

## The 11 Validation Checks Explained

### 1. YAML Front-Matter Extraction

The validator confirms that [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) begins with proper YAML front-matter using the regex pattern `r"\A---\n(.*?)\n---\n"`. This captures the metadata block between triple dashes. If the pattern fails to match, the script terminates immediately with a clear formatting error.

### 2. Forbidden Field Detection

Humanizer explicitly prohibits the fields **`compatibility:`** and **`allowed-tools:`** in its metadata. The script scans the captured YAML block using `re.search` for each forbidden field, raising `SystemExit` if either prohibited keyword appears, ensuring package metadata adheres strictly to supported specifications.

### 3. Cross-File Version Consistency

Version synchronization across three distinct files represents a critical integrity check. The script extracts version strings from:
- [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) metadata (YAML front-matter)
- [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) changelog section
- [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) manifest

It places these values into a Python set and validates that the set length equals exactly one. Any divergence triggers the error: `Use one package version in all files`, displaying the mismatched versions found.

### 4. Singular SKILL.md Enforcement

Using `rglob("SKILL.md")`, the validator searches the entire repository tree to ensure exactly one non-symlink [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file exists at the repository root. This prevents accidental duplication or symbolic link confusion that could break package resolution.

### 5. Claude Plugin Loader Configuration

The script verifies the Claude plugin manifest points to the correct skill location by checking that the `skills` field equals `"./"` in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json). This ensures the plugin loader references the repository root directory.

### 6. Plain Language Rules Compliance

Humanizer enforces specific writing guidelines defined in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md). The validator maintains a tuple of required plain-language rules and verifies each appears verbatim in the [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) file content. If any rules are missing, the script outputs `Add the missing Plain Language rules to AGENTS.md:` followed by the specific missing guidelines.

### 7. Pattern Numbering Sequence Validation

The [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file must contain exactly 35 numbered patterns without gaps or duplicates. The script extracts all pattern headings using the regex `(?m)^### ([0-9]+)\. ` and compares the resulting list against `range(1, 36)`. Any deviation from the sequential 1-35 range causes immediate validation failure.

### 8. README Table Consistency

Parallel to the skill file check, the validator confirms [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) contains a pattern table listing all 35 patterns. It extracts numbers from markdown table rows using `(?m)^\| ([0-9]+) \|` and verifies the set matches `range(1, 36)`, ensuring documentation completeness.

### 9. File Length Constraints

To maintain performance and readability standards, the script enforces a maximum of **500 lines** for [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). It counts lines using `SKILL.splitlines()` and raises an error if the count exceeds this limit, preventing skill bloat.

## Running the Validator Locally

Execute the validation script from the repository root to verify package integrity:

```bash
cd path/to/humanizer
python3 scripts/validate-package.py

```

Successful validation produces the confirmation message:

```bash
Humanizer package v1.2.3 is valid

```

The script requires no external dependencies or virtual environments, functioning immediately with any Python 3 installation.

## Interpreting Validation Failures

When checks fail, the validator provides specific, actionable error messages. For version mismatches between files:

```bash
$ python3 scripts/validate-package.py
Use one package version in all files: ['1.2.3', '1.2.4']

```

Missing plain-language rules trigger equally specific guidance:

```bash
Add the missing Plain Language rules to AGENTS.md: Use `must` for requirements.

```

Pattern numbering errors indicate exactly which sequence validation failed, allowing maintainers to pinpoint gaps or duplicates in the [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) structure without manual inspection.

## Summary

- **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)** performs 11 deterministic checks without external dependencies.
- **Version synchronization** requires identical strings across [`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).
- **Regex patterns** enforce YAML structure via `r"\A---\n(.*?)\n---\n"` and validate 35 sequential patterns using `(?m)^### ([0-9]+)\. `.

- **Forbidden fields** (`compatibility:` and `allowed-tools:`) are explicitly blocked from metadata.
- **Content constraints** include a 500-line limit for [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and mandatory presence of plain-language rules in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md).
- **Immediate failure** via `SystemExit` provides descriptive error messages for rapid debugging.

## Frequently Asked Questions

### What files does the Humanizer validator check?

The validator inspects four specific files: [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (skill definition and YAML metadata), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) (documentation and changelog), [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) (plain-language writing rules), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) (Claude plugin manifest). These files collectively define the Humanizer package structure and must remain internally consistent.

### Why does the script enforce a 500-line limit on SKILL.md?

The 500-line limit maintains skill conciseness and parsing performance. According to the source code at lines 85-87, the validator counts lines using `SKILL.splitlines()` and aborts if the count exceeds 500. This constraint prevents skill bloat and ensures the Claude plugin can efficiently process the skill definition.

### How does the validator detect version mismatches?

The script extracts version strings from three locations using specific regex patterns, stores them in a Python set, and verifies the set contains exactly one element. If multiple versions are detected (e.g., `1.2.3` in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) but `1.2.4` in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)), the set size exceeds one and the script exits with the message `Use one package version in all files` listing the discrepant values.

### What happens if a forbidden YAML field is detected?

If the validator discovers `compatibility:` or `allowed-tools:` fields in the [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) YAML front-matter, it immediately calls `SystemExit` with a descriptive error message. These fields are unsupported in Humanizer's metadata specification, and their presence indicates either legacy configuration or incorrect metadata structure that must be removed before validation can pass.