# What Is the Purpose of the scripts/validate-package.py Script in Humanizer?

> Discover the purpose of the scripts/validate-package.py script in Humanizer. This tool ensures package consistency by validating metadata, versions, and documentation.

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

---

**The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) utility is a lightweight, dependency-free validator that guarantees internal consistency across the Humanizer skill package by verifying YAML metadata, version alignment, and documentation integrity.**

In the `blader/humanizer` repository, maintaining synchronization between the core skill definition, plugin metadata, and user documentation is critical for reliable deployment. The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script serves as the automated gatekeeper that enforces these invariants before code reaches production. It is executed manually during development or as part of a CI step to catch version drift, malformed metadata, or structural mismatches early in the development cycle.

## Core Validation Checks Performed by validate-package.py

The validator performs ten distinct architectural checks across the repository's core files. Each check targets a specific file or metadata relationship to ensure the Humanizer skill package remains internally consistent.

### YAML Metadata and SCHEMA Compliance

At lines 25–28 in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), the script verifies that [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) begins with a proper YAML front-matter block. This ensures the Claude plugin system can correctly parse the skill's metadata headers.

Additionally, lines 30–33 explicitly disallow deprecated fields. The script rejects any presence of `compatibility:` or `allowed-tools:` keys, which have been removed from the current specification. This prevents legacy configuration from creeping back into the package.

### Cross-File Version Alignment

One of the most critical checks occurs at lines 34–43, where the script extracts and compares version strings across three distinct files:

- The `version` field in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)'s YAML header
- The first version entry listed in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)
- The `version` field in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)

If these values diverge, the script exits with a specific error message:

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

```

This prevents accidental version drift between the skill definition, documentation, and plugin descriptor.

### File Placement and Plugin Configuration

Lines 49–52 enforce repository structure by verifying that exactly one regular (non-symlink) [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) exists at the repository root. This eliminates ambiguity about which file the Claude plugin should load.

紧接着 (immediately following), lines 52–54 check that [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) correctly references the repository root in its `skills` array. The validator confirms the target is set to `"./"`, ensuring the plugin loader points to the correct directory relative to the configuration file.

### Content Integrity and Documentation Completeness

The script performs several content-level validations to maintain documentation quality:

**Plain-Language Rules Verification (lines 55–70):** The validator checks that all "Writing style" rules defined in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) are present in the package. This ensures the skill maintains consistent plain-language standards across all outputs.

**Pattern Numbering Sequence (lines 72–77):** [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) must contain numbered patterns forming a consecutive series from 1 to 35. The script validates this sequential integrity, ensuring no gaps or duplicates exist in the pattern definitions.

**README Table Completeness (lines 79–84):** The validator confirms that [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)'s pattern table lists every number from 1 through 35, matching the content in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md).

**File Size Enforcement (lines 85–87):** To maintain readability, [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) must not exceed 500 lines. The script counts lines and rejects files that exceed this limit.

When all checks pass, lines 88–89 generate a confirmation message:

```bash
$ python3 scripts/validate-package.py
Humanizer package v1.4.2 is valid

```

## How to Run the Humanizer Package Validator

Executing the validator requires no external dependencies beyond Python 3. From the repository root, run:

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

```

Any validation failure produces an immediate, specific error message indicating which invariant was violated.

### CI Integration

For automated checking, integrate the script into your continuous integration workflow:

```yaml
- name: Validate Humanizer package
  run: python3 scripts/validate-package.py

```

This ensures that pull requests cannot be merged if they introduce version mismatches, malformed YAML, or missing documentation entries.

## Integration with the Humanizer Repository Architecture

The validator acts as the enforcement mechanism for the public contract between [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json), and [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md). By codifying these relationships in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), the repository maintains a single source of truth for:

- The canonical skill definition in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
- Human-readable documentation in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)  
- Claude-specific plugin metadata in [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)
- Writing style standards defined in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md)

This architectural boundary prevents the "documentation rot" common in multi-file projects where metadata and content gradually desynchronize over time.

## Summary

- **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)** is a dependency-free Python script that validates the structural integrity of the Humanizer skill package.
- It enforces **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).
- The script validates **YAML metadata** structure while rejecting deprecated fields like `compatibility:` and `allowed-tools:`.
- It verifies **content completeness**, ensuring consecutive pattern numbering (1–35), complete README tables, and presence of plain-language rules from [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md).
- **File placement** checks ensure a single [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) exists at the repository root and the plugin loader points to `"./"`.
- A **500-line limit** on [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) prevents documentation bloat and maintains readability.

## Frequently Asked Questions

### What files does validate-package.py check?

The script validates four primary files: [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (the core skill definition), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) (documentation and version entry), [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) (plugin descriptor), and [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) (writing style rules). It specifically checks for YAML headers in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), version strings across the first three files, and rule presence in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md).

### How does the script handle version mismatches?

When versions differ between [`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 exits with a non-zero status and displays the conflicting version numbers in a list format: `Use one package version in all files: ['1.4.2', '1.5.0']`. This prevents packages with inconsistent versioning from passing validation.

### Can I use this validator for other Claude skill packages?

While designed specifically for the `blader/humanizer` repository structure, the script can be adapted for other Claude skill packages that follow similar conventions: a single [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) with YAML front matter, a [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) with a version entry, and a [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) configuration. However, hardcoded values like the 35-pattern sequence or 500-line limit would require modification for different projects.

### What happens if SKILL.md exceeds 500 lines?

The script performs a line count check at lines 85–87. If [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains more than 500 lines, the validator exits with an error indicating the file is too long. This enforces the repository's readability standards and prevents the skill definition from becoming unwieldy.