feat(zod): add use-zod skill plugin

[amondnet]

Summary

Adds a new built-in zod plugin at plugins/zod/, following the same pattern established in PR #161 (mastra) and PR #159 (better-auth). No MCP server — the plugin is a pure skills-only plugin, identical in structure to both precedents.

What's New

Plugin layout

plugins/zod/ mirrors plugins/mastra/ and plugins/better-auth/:

• .claude-plugin/plugin.json — plugin manifest (name, version, description, author, homepage, repository, license, keywords)
• skills/use-zod/SKILL.md — main skill definition; activates when Zod schemas, validation, or parsing are mentioned

Skill files (4 total)

File	Purpose
skills/use-zod/SKILL.md	Skill definition — trigger patterns, usage guide, when to prefer Zod, version detection
skills/use-zod/versions.md	Side-by-side Zod v3 vs v4 API reference; acts as a quick cheatsheet
skills/use-zod/schemas.md	Schema construction patterns for primitives, objects, arrays, unions, transforms, refinements
skills/use-zod/parsing-and-errors.md	Parsing methods (.parse, .safeParse, .parseAsync) and error handling

No MCP server

Zod is a pure schema-validation library with stable, well-documented APIs. A skill providing inline reference is sufficient; no runtime server is needed.

v3 ↔ v4 migration callouts surfaced in the skill

• format / flatten → treeifyError / flattenError / prettifyError
• Separate message / errorMap issue params → unified error param
• z.lazy + TypeScript annotation → property getter pattern for recursive schemas
• .superRefine deprecated → .check
• New in v4: z.codec, .overwrite, zod/mini lightweight build

ask CLI integration (mirrors better-auth from PR #159)

The skill instructs Claude to resolve version-accurate docs and source via the ask CLI tool first (ask_public_library zod), falling back to node_modules/zod/. This ensures advice reflects the installed version rather than training-data snapshot.

Registry changes

File	Change
.claude-plugin/marketplace.json	New entry for zod plugin
release-please-config.json	New component plugins/zod
README.md	Added zod to the built-in plugins table

New files

plugins/zod/.claude-plugin/plugin.json
plugins/zod/skills/use-zod/SKILL.md
plugins/zod/skills/use-zod/versions.md
plugins/zod/skills/use-zod/schemas.md
plugins/zod/skills/use-zod/parsing-and-errors.md

Modified registry files

.claude-plugin/marketplace.json
release-please-config.json
README.md

Verification

claude plugin validate plugins/zod passes. The homepage/repository warning visible in CI output is a pre-existing issue on main (affects other plugins as well) and is unrelated to this PR.

---

Summary by cubic

Adds a built-in zod skills-only plugin with version-aware help for Zod v3 and v4 (schemas, parsing, errors, and migrations). Mirrors the mastra/better-auth pattern, uses ask for version detection, and requires no MCP server.

• New Features

  • New plugins/zod/ with skills/use-zod/ and references/ (schemas, parsing-and-errors, versions) covering common APIs, error handling, and v3↔v4 differences.
  • Version detection via ask (ask src zod, ask docs zod) with node_modules/zod/ fallback.
  • Migration notes: err.format/err.flatten → z.treeifyError/z.flattenError; { message, errorMap } → { error }; recursion via getters; new z.codec (v4.1+), .overwrite, and zod/mini.
  • Registered in .claude-plugin/marketplace.json, added release config in release-please-config.json, and updated README.

• Bug Fixes

  • Corrected guidance: .superRefine remains the recommended multi-issue API in v4; .check is a lower-level, performance-focused alternative.
  • Docs/metadata fixes: corrected Zod v4 release year (2025), fixed a recursive example to use a self-referencing variable, and updated plugin author to upstream Zod.

^{Written for commit 0af26ed. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
claude-code-plugins	Ready	Preview, Comment	Apr 29, 2026 7:35pm

[gemini-code-assist]

Code Review

This pull request introduces a new plugin for Zod, including a comprehensive skill set and reference documentation for both v3 and v4. The changes include updates to the marketplace configuration, README, and release-please settings. Several critical issues were identified in the documentation regarding incorrect versioning claims (hallucinating a 2026 release date for v4 and non-existent version numbers) and the misidentification of the current stable version. Additionally, the plugin metadata needs to be updated to credit the upstream organization rather than an individual contributor.

[cubic-dev-ai]

3 issues found across 8 files

Confidence score: 4/5

• This PR is safe to merge; all noted issues are documentation inaccuracies with low to moderate user impact.
• Most significant: plugins/zod/skills/use-zod/references/versions.md has an invalid recursive schema example (Self is undefined), which could mislead readers copying the v4 snippet.
• Also in plugins/zod/skills/use-zod/references/parsing-and-errors.md, the .loose() API call is incorrect for v4 and should be z.looseObject(...) or legacy .passthrough().
• Pay close attention to plugins/zod/skills/use-zod/references/versions.md, plugins/zod/skills/use-zod/references/parsing-and-errors.md, plugins/zod/skills/use-zod/SKILL.md - fix v4 example/API usage and release-year accuracy.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="plugins/zod/skills/use-zod/references/versions.md">

<violation number="1" location="plugins/zod/skills/use-zod/references/versions.md:84">
P2: The recursive schema example uses `Self`, which is undefined. This makes the v4 example invalid when copied; the getter should reference the schema variable itself.</violation>
</file>

<file name="plugins/zod/skills/use-zod/SKILL.md">

<violation number="1" location="plugins/zod/skills/use-zod/SKILL.md:34">
P3: Correct the Zod v4 release year; the current text says 2026, but official docs place the v4 root/npm transition in 2025.</violation>
</file>

<file name="plugins/zod/skills/use-zod/references/parsing-and-errors.md">

<violation number="1" location="plugins/zod/skills/use-zod/references/parsing-and-errors.md:225">
P2: The v4 migration guidance references `.loose()`, which is not a Zod v4 object API; use `z.looseObject(...)` (or legacy `.passthrough()`) instead.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as "User / Claude"
    participant Skill as "NEW: Zod Skill Plugin"
    participant Ask as "ask CLI Tool"
    participant FS as "Local Filesystem (node_modules)"
    participant Cache as "ask Cache (~/.ask/)*"

    Note over User,Cache: Runtime Skill Activation (Trigger: "zod", "z.object", etc.)

    User->>Skill: "How do I format errors in this project?"
    
    Skill->>FS: "NEW: Check installed version (package.json)"
    FS-->>Skill: "Return version (e.g., v4.3.6)"

    alt "NEW: ask CLI available"
        Skill->>Ask: "ask src zod / ask docs zod"
        Ask->>FS: "Resolve version from lockfile"
        alt "Data not in cache"
            Ask->>Ask: "Fetch version-accurate source/docs"
            Ask->>Cache: "Store source/docs"
        end
        Ask-->>Skill: "Return paths ($SRC, $DOCS)"
        
        Skill->>Cache: "NEW: Search symbols/tests (rg/fd)"
        Cache-->>Skill: "API signatures & usage examples"
    else "fallback: ask CLI missing"
        Skill->>FS: "Inspect node_modules/zod/dist"
        FS-->>Skill: "Return compiled output/types"
    end

    Note over Skill: "NEW: Branch logic based on version (v3 vs v4)"

    alt "Version is v4"
        Skill->>Skill: "CHANGED: Select v4 APIs (treeifyError, .check())"
    else "Version is v3"
        Skill->>Skill: "Select v3 APIs (err.format(), .superRefine())"
    end

    Skill-->>User: "Return version-accurate advice & migration callouts"

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}