What Does the Humanizer validate.yml GitHub Actions Workflow Do?

The validate.yml workflow in the blader/humanizer repository is a CI pipeline that automatically verifies package integrity, ensures version consistency across documentation files, and validates Claude marketplace compatibility on every pull request and push to main.

The blader/humanizer project maintains a curated set of patterns for humanizing AI-generated content, and the .github/workflows/validate.yml file serves as the automated gatekeeper that prevents broken releases and documentation drift. This workflow orchestrates multiple validation layers—from internal consistency checks to third-party tool compatibility—to ensure the skill remains discoverable and ready for production use.

Workflow Triggers and Permissions

The pipeline activates on two primary events according to the on: section of .github/workflows/validate.yml:

• Pull requests: Every PR triggers the full validation suite to catch issues before merge
• Pushes to main: Direct commits to the default branch undergo the same scrutiny to maintain repository integrity

Security is enforced through minimal permissions. The workflow grants only contents: read access, ensuring the runner can checkout code but cannot modify repository state. This read-only approach aligns with security best practices for CI pipelines that only perform verification tasks.

Multi-Language Environment Setup

The validation job runs on ubuntu-latest and configures two runtime environments required for the complete check suite:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

Node.js 22 powers the skill discovery verification using the official skills CLI, while Python 3.12 executes the internal validation logic in scripts/validate-package.py. This dual-environment setup reflects the heterogeneous tooling ecosystem that consumes the Humanizer package.

Package Consistency Validation

The core logic resides in python3 scripts/validate-package.py, which performs rigorous structural checks on the Humanizer skill definition:

• Metadata validation: Confirms SKILL.md begins with proper YAML frontmatter containing required fields
• Version synchronization: Ensures version numbers match exactly across SKILL.md, README.md, and .claude-plugin/plugin.json
• Pattern integrity: Verifies pattern numbers are consecutive and that README tables accurately reflect the patterns defined in the skill file
• Structural constraints: Enforces length limits and formatting rules that prevent parser errors in downstream consumers

This step catches the most common integration failures: documentation drift where the README describes patterns that no longer exist in the actual skill definition, or version mismatches that break automated update mechanisms.

Skill Discovery and Marketplace Checks

Beyond internal consistency, the workflow validates external tool compatibility through two specialized checks:

Skill Discovery Verification

npx --yes skills@1.5.20 add . --list

This command uses the official skills CLI (version 1.5.20) to verify the package can be discovered and added to an agent's skillset. If this step fails, the skill would be invisible to compatible AI agents despite being technically valid.

Claude Marketplace Validation

npm install --global @anthropic-ai/claude-code@2.1.237
claude plugin validate .

The workflow installs the Claude Code CLI (version 2.1.237) and runs claude plugin validate . against the .claude-plugin/plugin.json descriptor. This ensures the plugin meets Anthropic's marketplace schema requirements and will function correctly when installed by Claude users.

Why the validate.yml Workflow Matters

The comprehensive validation strategy in .github/workflows/validate.yml prevents three critical failure modes:

• Broken releases: Catches version inconsistencies or malformed pattern tables before they reach the main branch
• Documentation decay: Ensures README.md examples remain synchronized with the actual SKILL.md implementation
• Ecosystem fragmentation: Guarantees the skill works with both the skills CLI discovery mechanism and the Claude marketplace, preventing "works on my machine" scenarios for AI agent builders

By blocking merges that fail these checks, the repository maintains the contract expected by automated tools consuming the Humanizer skill.

Summary

• The validate.yml workflow triggers on every pull request and push to main, running on ubuntu-latest with read-only permissions
• It validates internal consistency via scripts/validate-package.py, checking YAML metadata, version alignment across three files, and pattern numbering
• External compatibility is verified using npx skills@1.5.20 for discovery and claude plugin validate for marketplace compliance
• The pipeline requires both Node.js 22 and Python 3.12 environments to execute the full validation suite
• This CI configuration protects the blader/humanizer repository from documentation drift and ecosystem integration failures

Frequently Asked Questions

What files does the Humanizer validation script check?

The scripts/validate-package.py script validates four critical files: SKILL.md (the core skill definition), README.md (documentation), .claude-plugin/plugin.json (Claude marketplace descriptor), and its own validation logic. It specifically enforces that version numbers remain identical across the first three files and that pattern tables in the README match the patterns defined in SKILL.md.

Why does the workflow use both Node.js and Python?

The workflow requires Node.js 22 to execute the skills CLI tool (npx skills@1.5.20) for skill discovery verification, and Python 3.12 to run the validate-package.py script that checks internal package consistency. This reflects the dual ecosystem nature of the project, which must satisfy both Node.js-based AI tooling and Python-based validation logic.

What permissions does the validate.yml workflow require?

The workflow operates with minimal security privileges, requesting only contents: read permission in the permissions: block. This read-only access allows the runner to checkout the repository code but prevents any modifications, ensuring the validation pipeline cannot accidentally alter repository state or be exploited for unauthorized writes.

How does the workflow ensure Claude marketplace compatibility?

The final step installs the official @anthropic-ai/claude-code package (version 2.1.237) globally and executes claude plugin validate . against the repository root. This validates the .claude-plugin/plugin.json descriptor against Anthropic's current marketplace schema, ensuring the Humanizer skill will install correctly for Claude Code users without schema errors.

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