# What Does the GitHub Actions Workflow in `.github/workflows/validate.yml` Do?

> Discover the role of the .github/workflows/validate.yml GitHub Actions workflow in the blader/humanizer repository. It automatically validates the skill package for consistency and marketplace compatibility.

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

---

**The [`validate.yml`](https://github.com/blader/humanizer/blob/main/validate.yml) workflow in the `blader/humanizer` repository defines a continuous integration pipeline that automatically validates the skill package on every push and pull request to ensure metadata consistency, skill discoverability, and Claude marketplace compatibility.**

This workflow serves as the primary quality gate, executing four distinct validation stages defined in [`.github/workflows/validate.yml`](https://github.com/blader/humanizer/blob/main/.github/workflows/validate.yml) to verify that the repository remains in a publishable state before any changes merge into the `main` branch.

## Workflow Triggers and Permissions

The pipeline triggers on two specific GitHub events: every **push to the `main` branch** and every **pull request** targeting `main`. This configuration ensures that no code reaches the default branch without passing all automated checks.

Security is enforced through a restrictive `permissions` block configured at lines 8-9 of the workflow file. The job operates with **read-only** access to repository contents, preventing any accidental write operations during the CI process.

## Validation Pipeline Steps

The workflow executes four sequential stages, each designed to catch specific categories of errors before they reach production.

### Environment Setup

First, the workflow prepares the execution environment by installing the required runtimes. At line 15, it checks out the repository using `actions/checkout`, then configures **Node.js 22** (lines 16-19) and **Python 3.12** (lines 20-21). This dual-runtime setup supports both the JavaScript-based Claude tooling and the Python validation scripts.

### Package Integrity Verification

The second step executes [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) (lines 22-23) to verify internal consistency between critical metadata files. This Python script ensures that [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) remains synchronized with [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) and validates other package metadata required for the Humanizer skill to function correctly. Any divergence between these files causes the workflow to fail immediately.

### Skill Discovery Check

At lines 24-25, the workflow verifies that the skill can be correctly discovered by the Skills CLI. It executes:

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

```

This command confirms that the skill package structure matches the expected schema and that the generated skill list contains the Humanizer entry. Failure here indicates the skill would not be discoverable by compatible agents.

### Claude Marketplace Validation

The final stage (lines 26-29) validates compatibility with Anthropic's plugin ecosystem. The workflow installs `@anthropic-ai/claude-code@2.1.237` globally, then runs:

```bash
claude plugin validate .

```

This check inspects [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) and [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) to ensure both files are well-formed and meet Claude's marketplace requirements. This validation guarantees the plugin can be distributed through official channels without deployment errors.

## Running Validation Locally

Contributors can reproduce the complete CI pipeline locally using the same tools and versions defined in the workflow:

```bash

# Install required runtimes

nvm install 22
pyenv install 3.12.0

# Step 1: Validate package integrity

python3 scripts/validate-package.py

# Step 2: Verify skill discovery

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

# Step 3: Validate Claude marketplace configuration

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

```

Executing these commands before pushing ensures that local changes will pass the automated checks in the GitHub Actions workflow.

## Summary

- The [`.github/workflows/validate.yml`](https://github.com/blader/humanizer/blob/main/.github/workflows/validate.yml) file defines a **CI pipeline** triggered on pushes and pull requests to the `main` branch.
- The workflow maintains **read-only permissions** to prevent accidental repository modifications during validation.
- Four validation stages check **environment setup**, **package integrity** via [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), **skill discovery** via the Skills CLI, and **Claude marketplace compatibility**.
- The pipeline validates critical files including [`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 [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json).
- All checks can be reproduced locally using Node.js 22, Python 3.12, and the specific CLI versions referenced in the workflow.

## Frequently Asked Questions

### When does the validate.yml workflow run?

The workflow triggers automatically on every push to the `main` branch and on every pull request targeting `main`. This configuration ensures that no changes can be merged without passing all four validation stages defined in the file.

### What specific files does the package validation script check?

The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script validates that [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) remain synchronized, along with other metadata files required for the Humanizer skill package. Any inconsistency between these documentation files causes the CI job to fail at lines 22-23 of the workflow.

### Why does the workflow require both Node.js and Python?

The workflow uses **Node.js 22** to run the Skills CLI discovery tool and the Claude Code validation commands, while **Python 3.12** executes the internal package integrity script. This dual-runtime approach accommodates the heterogeneous toolchains required by the Claude plugin ecosystem and the Humanizer validation logic.

### How can I validate the Claude marketplace configuration locally?

Install the specific Claude Code CLI version using `npm install --global @anthropic-ai/claude-code@2.1.237`, then run `claude plugin validate .` from the repository root. This command checks that [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) and [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) are properly formatted for the Claude marketplace, identical to the check performed at lines 26-29 of the workflow file.