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

> Discover how the validate.yml GitHub Actions workflow in blader/humanizer ensures package integrity, version consistency, and marketplace compatibility on every pull request and push.

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

---

**The [`validate.yml`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/.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:

```yaml
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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) begins with proper YAML frontmatter containing required fields
- **Version synchronization**: Ensures version numbers match exactly 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 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**

```bash
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**

```bash
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`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/README.md) examples remain synchronized with the actual [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script validates four critical 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), [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/.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.