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

The Humanizer script validates package files by running 11 deterministic checks in scripts/validate-package.py to ensure YAML metadata integrity, version consistency across SKILL.md, README.md, and .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, a standalone script that loads and inspects four critical repository files: SKILL.md, README.md, AGENTS.md, and .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 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 metadata (YAML front-matter)
• README.md changelog section
• .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 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. This ensures the plugin loader references the repository root directory.

6. Plain Language Rules Compliance

Humanizer enforces specific writing guidelines defined in AGENTS.md. The validator maintains a tuple of required plain-language rules and verifies each appears verbatim in the 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 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 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. 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:

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

Successful validation produces the confirmation message:

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:

$ 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:

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 structure without manual inspection.

Summary

• scripts/validate-package.py performs 11 deterministic checks without external dependencies.

• Version synchronization requires identical strings across SKILL.md, README.md, and .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 and mandatory presence of plain-language rules in 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 (skill definition and YAML metadata), README.md (documentation and changelog), AGENTS.md (plain-language writing rules), and .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 but 1.2.4 in 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 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.

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