Validation Workflow

Two layers of validation before a PR ships: local commands the contributor runs, and CI that catches regressions on every PR.

Local validation (before opening a PR)

1. Validate the changed plugin

claude plugin validate ./plugins/<plugin>

Catches:

• Missing or malformed plugin.json
• SKILL.md files with invalid frontmatter
• Broken JSON schema, missing required fields
• File-name to name-field mismatches

2. Validate the marketplace manifest

claude plugin validate .

Catches:

• .claude-plugin/marketplace.json syntax errors
• Plugin entries pointing at directories that don’t exist
• Mis-spelled plugin names

3. Smoke-test the change

claude --plugin-dir ./plugins/<plugin>

Inside the launched session:

• Run /plugins list and confirm the plugin appears as inline · ✓ enabled
• Invoke any new or modified skill end-to-end with realistic input
• For rule changes: run a few prompts that should be affected by the rule and verify Claude applies it
• For agent changes: trigger the agent (or have a skill delegate to it) and verify the output shape

If the smoke test reveals issues that local validate missed, the validator has a gap — flag it in the PR description.

CI validation (on every PR)

CodeBuild runs buildspec.yml on PR events. The current V1 buildspec is a placeholder; real validators land in V1.5. Once they ship, CI will run:

• validate-marketplace.ts — manifest correctness
• validate-frontmatter.ts — every SKILL.md has required frontmatter
• check-marketplace-sorted.ts — plugins[] array is alphabetically sorted

Until the real validators land, assume CI catches nothing — local validation is the only line of defense. See CI Validators for the V1.5 plan.

PR checklist

Before opening the PR:

• claude plugin validate ./plugins/<changed-plugin> passes
• claude plugin validate . passes
• Smoke test completed in a fresh --plugin-dir session
• If the change adds a new plugin: marketplace.json entry added in alphabetical order
• If the change adds a user-facing artifact: docs site page updated (if applicable)
• PR description has a one-line reason for the change

When validation fails on something that looks fine

If the validator complains about a file that looks correct, check:

• YAML indent — frontmatter requires exact indentation; a stray tab breaks parsing
• Trailing whitespace in YAML keys — name : foo (with space before colon) fails
• kebab-case names — name: My Skill fails; name: my-skill passes
• Description as multi-line YAML — wrap long descriptions in single quotes or use the > folded-scalar syntax

If the validator gives an unhelpful error, escalate via the same path as feature requests (CodeCommit issue or message Felix on Teams).