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

The 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 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 (lines 22-23) to verify internal consistency between critical metadata files. This Python script ensures that SKILL.md remains synchronized with 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:

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:

claude plugin validate .

This check inspects .claude-plugin/plugin.json and 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:

# 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 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, skill discovery via the Skills CLI, and Claude marketplace compatibility.
• The pipeline validates critical files including SKILL.md, README.md, .claude-plugin/plugin.json, and 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 script validates that SKILL.md and 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 and marketplace.json are properly formatted for the Claude marketplace, identical to the check performed at lines 26-29 of the workflow file.

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