Plugin Validation Workflow

This page documents the validate-plugin.yml GitHub Actions workflow, which validates the Claude plugin manifest and configuration files in the repository. It covers triggers, steps, and what each check verifies.

For context on the marketplace.json manifest structure and its fields, see 5.3. For how the plugin is installed in Claude Desktop, see 6.1. For the other CI/CD workflows, see 9.1, 9.2, and 9.3.

---

Purpose

The workflow ensures that the .claude-plugin/marketplace.json manifest remains valid whenever changes are made to it or to package.json. It runs two categories of checks:

1. Structural validation via the claude CLI tool (claude plugin validate)
2. Existence and JSON syntax checks using shell commands and jq

Without this workflow, a malformed or missing manifest could break Claude plugin marketplace installation for end users without any CI signal.

---

Triggers

Workflow file: .github/workflows/validate-plugin.yml1-12

The workflow fires on two GitHub events, both scoped to specific path patterns:

Event	Branch	Paths
pull_request	any	.claude-plugin/**, package.json
push	main	.claude-plugin/**, package.json

The package.json path is included because the plugin manifest references the package version, and a version bump there may require the manifest to be updated in sync.

Diagram: Trigger Conditions

Sources: .github/workflows/validate-plugin.yml1-12

---

Job: validate

The single job validate runs on ubuntu-latest and executes four steps sequentially.

Diagram: Step Sequence in the validate Job

Sources: .github/workflows/validate-plugin.yml14-46

---

Step 1: Checkout

uses: actions/checkout@v6

Standard checkout. No special options.

Sources: .github/workflows/validate-plugin.yml19-21

---

Step 2: Setup Node.js

uses: actions/setup-node@v6
with:
 node-version: '20'

Node 20 is required for the Claude CLI package. This mirrors the Node version used in the test and publish workflows.

Sources: .github/workflows/validate-plugin.yml22-26

---

Step 3: Install Claude CLI

.github/workflows/validate-plugin.yml27-29

npm install -g @anthropic-ai/claude-code

Installs the claude binary globally. This is the Anthropic Claude Code CLI, which includes the claude plugin validate subcommand used in the next step.

---

Step 4: claude plugin validate

.github/workflows/validate-plugin.yml30-31

claude plugin validate .

Runs the CLI validator against the repository root (.). The CLI reads the .claude-plugin/ directory and validates the manifest schema, the mcpServers configuration block, and any other plugin-specific constraints enforced by Anthropic's tooling.

This is the primary semantic check. It catches issues like missing required fields, incorrect mcpServers structure, or unsupported transport types.

---

Step 5: File Existence Check

.github/workflows/validate-plugin.yml33-39

A simple shell guard that fails the job with exit code 1 if .claude-plugin/marketplace.json is absent. This is a redundant safety net — claude plugin validate would likely catch this too, but the explicit check provides a clearer error message.

---

Step 6: JSON Syntax Validation

.github/workflows/validate-plugin.yml41-45

jq empty exits with a non-zero code if the input is not valid JSON. It emits no output on success. This catches syntax errors (trailing commas, unquoted keys, etc.) that might not produce obvious failures in the CLI validator.

---

What Gets Validated

Diagram: Validation Targets and Checks

Sources: .github/workflows/validate-plugin.yml14-46 .claude-plugin/marketplace.json1-48

---

The marketplace.json Manifest

The file being validated is .claude-plugin/marketplace.json1-48 Its top-level structure:

Field	Value
name	"perplexity-mcp-server"
owner.name	"Perplexity AI"
metadata.version	"0.8.3"
plugins[0].name	"perplexity"
plugins[0].license	"MIT"
plugins[0].category	"productivity"
plugins[0].strict	false

The mcpServers block inside plugins[0] .claude-plugin/marketplace.json35-44 declares the stdio transport:

PERPLEXITY_TIMEOUT_MS defaults to 600000 (10 minutes) in this manifest, which differs from the global server default of 300000 (5 minutes). This higher timeout accommodates sonar-deep-research latencies within the Claude plugin context.

Sources: .claude-plugin/marketplace.json1-48

---

Relationship to Other Workflows

Workflow	File	Shares Trigger Path?
Test	.github/workflows/test.yml	No (triggers on all files)
NPM Publish	.github/workflows/publish.yml	Yes (package.json)
MCP Registry Publish	.github/workflows/publish-mcp.yml	Yes (package.json)
Plugin Validate	.github/workflows/validate-plugin.yml	— (.claude-plugin/**, package.json)

When package.json changes on main, the NPM publish, MCP registry publish, and plugin validate workflows all run concurrently. The plugin validate workflow is purely read-only — it does not publish or mutate any external registry.

Sources: .github/workflows/validate-plugin.yml1-12