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

The 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 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, the script verifies that 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's YAML header
• The first version entry listed in README.md
• The version field in .claude-plugin/plugin.json

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

$ 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 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 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 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 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's pattern table lists every number from 1 through 35, matching the content in SKILL.md.

File Size Enforcement (lines 85–87): To maintain readability, 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:

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

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:

- 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, README.md, .claude-plugin/plugin.json, and AGENTS.md. By codifying these relationships in scripts/validate-package.py, the repository maintains a single source of truth for:

• The canonical skill definition in SKILL.md
• Human-readable documentation in README.md
• Claude-specific plugin metadata in .claude-plugin/plugin.json
• Writing style standards defined in 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 is a dependency-free Python script that validates the structural integrity of the Humanizer skill package.
• It enforces version consistency across SKILL.md, README.md, and .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.
• File placement checks ensure a single SKILL.md exists at the repository root and the plugin loader points to "./".
• A 500-line limit on 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 (the core skill definition), README.md (documentation and version entry), .claude-plugin/plugin.json (plugin descriptor), and AGENTS.md (writing style rules). It specifically checks for YAML headers in SKILL.md, version strings across the first three files, and rule presence in AGENTS.md.

How does the script handle version mismatches?

When versions differ between SKILL.md, README.md, and .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 with YAML front matter, a README.md with a version entry, and a .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 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.

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