Skip to main content
skill CX Codex

zod-validation — Claude Code skill: what it does, how to install

zod-validation guides AI coding agents through Zod v4 schema validation in TypeScript. Helps write schemas, parse incoming payloads, and generate JSON Schema definitions.

MIT 222 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill zod-validation -a claude-code
Open on GitHub

What zod-validation does

Zod v4 changes multiple established patterns across TypeScript projects. It introduces standalone format functions like z.email() and z.url(), replaces z.lazy() with getter-based recursion, and brings built-in file validation via z.file(). This skill keeps the agent updated on these syntax updates to prevent generating obsolete v3 code.

The reference material covers fixed-width numbers, ISO date validators, and error tree formatting via z.treeifyError(). It also reminds the model that z.record() now requires two arguments and that z.number() rejects Infinity values.

Keep in mind this skill focuses purely on schema contracts and validation logic. When form-specific workflows are needed, the documentation advises delegating to the tanstack-form skill.

What it helps with

  • define data contracts using Zod v4 syntax
  • convert TypeScript validation schemas to JSON Schema
  • validate file uploads and ISO timestamps
  • migrate legacy v3 schema definitions to getter recursion

Example prompts for the agent

  • Create a Zod v4 schema for an onboarding payload with email, website URL, and avatar file
  • Transform this product schema into JSON Schema using z.toJSONSchema()
  • Refactor this recursive tree structure to use Zod v4 getter syntax instead of z.lazy

How to install zod-validation

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill zod-validation -a claude-code

2Manually: put the files in place

~/.claude/skills/zod-validation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/zod-validation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about zod-validation

How do I install zod-validation in Claude Code?

Run npx skills add oakoss/agent-skills --skill zod-validation -a claude-code in your project terminal.

What changed in Zod v4 according to this skill?

Version 4 switches string formats like email to top-level calls, enforces two arguments for z.record(), and drops z.lazy() in favor of getter-based recursive definitions.

Does this skill handle web forms directly?

No, it handles schema contracts and parsing logic only. Form integration workflows should be handed over to the tanstack-form skill.

Source text

SKILL.md · MIT
---
name: zod-validation
description: 'Zod v4 schema validation for TypeScript. Covers primitives, string formats, objects, arrays, unions, coercion, transforms, refinements, parsing, type inference, error customization, JSON Schema, file validation, and metadata. Use when writing schemas, validating input, parsing data, inferring types, or converting schemas with Zod.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: https://zod.dev
user-invocable: false
---

# Zod Validation (v4)

Type-safe schema validation for TypeScript. Zod v4 introduces top-level format functions, `z.stringbool()`, `z.iso.*` date formats, `z.overwrite()` transforms, `z.file()`, `z.toJSONSchema()`, getter-based recursive types, `.meta()`, and the unified `error` function.

**Package:** `zod` (also `zod/mini` for smaller bundles)

## Quick Reference

| Pattern                                    | Usage                                          |
| ------------------------------------------ | ---------------------------------------------- |
| `z.object({ ... })`                        | Define object schemas                          |
| `z.string()`, `z.number()`                 | Primitive types                                |
| `z.email()`, `z.url()`, `z.uuid()`         | Top-level string formats (v4)                  |
| `z.iso.date()`, `z.iso.datetime()`         | ISO date/time formats (v4)                     |
| `z.int()`, `z.float32()`, `z.int32()`      | Fixed-width number formats (v4)                |
| `z.templateLiteral([...])`                 | Template literal type validation (v4)          |
| `z.enum([...])`, `z.literal()`             | Enums and literals                             |
| `z.union([...])`, `z.discriminatedUnion()` | Union types                                    |
| `z.array()`, `z.tuple()`                   | Array and tuple types                          |
| `z.record()`, `z.map()`                    | Key-value collections                          |
| `.optional()`, `.nullable()`               | Optional and nullable modifiers                |
| `.default()`, `.catch()`                   | Default values and fallbacks                   |
| `.prefault()`                              | Pre-parse default (parsed through schema, v4)  |
| `z.coerce.number()`                        | Type coercion before validation                |
| `z.stringbool()`                           | String-to-boolean parsing (v4)                 |
| `.transform()`, `.overwrite()`             | Output transforms                              |
| `z.pipe()`                                 | Chain schemas (output feeds next input)        |
| `.refine()`, `.superRefine()`              | Custom validation logic                        |
| `.parse()`, `.safeParse()`                 | Validate and extract data                      |
| `z.infer<typeof Schema>`                   | Extract TypeScript type from schema            |
| `z.input<>`, `z.output<>`                  | Input vs output types with transforms          |
| `z.file()`                                 | File instance validation (v4)                  |
| `z.toJSONSchema()`                         | Convert schema to JSON Schema (v4)             |
| `.meta()`, `.describe()`                   | Attach metadata to schemas (v4)                |
| `z.prettifyError()`                        | Human-readable error formatting (v4)           |
| `z.treeifyError()`                         | Structured error tree (replaces .format(), v4) |
| `z.registry()`                             | Typed schema registry (v4)                     |
| `{ error: (issue) => ... }`                | Unified error customization (v4)               |
| Getter-based recursion                     | Recursive types without `z.lazy()` (v4)        |
| `z.globalRegistry`                         | Global schema metadata registry (v4)           |
| `z.config(z.locales.en())`                 | Internationalized error messages (v4)          |

## Common Mistakes

| Mistake                                 | Fix                                                           |
| --------------------------------------- | ------------------------------------------------------------- |
| `z.string().email()`                    | `z.email()` (v4 top-level format)                             |
| `z.string().url()`                      | `z.url()` (v4 top-level format)                               |
| Using `parse` without try/catch         | Use `safeParse` for error handling                            |
| Forgetting `.optional()`                | Add when field may be undefined                               |
| `z.any()` for unknown data              | Use `z.unknown()` for type-safe unknown                       |
| `.transform()` for same-type changes    | Use `.overwrite()` (introspectable, v4)                       |
| Missing `.min(1)` on strings            | Empty strings pass `z.string()` by default                    |
| `z.number().parse(Infinity)`            | `z.number()` rejects `Infinity` in v4                         |
| `z.number().safe()` for floats          | `.safe()` equals `.int()` in v4 (no floats)                   |
| `z.lazy()` for recursive types          | Use getter syntax in v4 (retains object methods)              |
| `required_error` / `invalid_type_error` | Use unified `error` function in v4                            |
| `.refine(fn, (val) => ({ message }))`   | Function-as-second-arg overload removed; use `.superRefine()` |
| `errorMap` on schemas                   | Replaced by `error` function in v4                            |
| `z.record(z.string())` single arg       | v4 requires two args: `z.record(z.string(), z.string())`      |
| `.format()` / `.flatten()` on ZodError  | Deprecated; use `z.treeifyError(err)` in v4                   |
| `.default()` with input type value      | v4 `.default()` uses output type; use `.prefault()` for input |

## Delegation

Use this skill for Zod schema definition, validation, parsing, type inference, coercion, error formatting, metadata, and JSON Schema conversion. For form integration, delegate to the tanstack-form skill.

## References

- [Schema Types](references/schema-types.md) — primitives, string formats, number formats, template literals, objects, arrays, enums, unions, records, optional, nullable
- [Transforms and Parsing](references/transforms-and-parsing.md) — coercion, stringbool, transforms, overwrite, pipe, refinements, parsing, type inference
- [Error Handling](references/error-handling.md) — unified error function, prettifyError, treeifyError, ZodError, error formatting, internationalization
- [Common Patterns](references/common-patterns.md) — form validation, API responses, environment variables, schema composition, recursive types, branded types
- [Metadata and JSON Schema](references/metadata-and-json-schema.md) — meta, describe, globalRegistry, toJSONSchema, file validation, Zod Mini

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Backend and APIs →

From the same set106

The whole set →
brand-designer brand-designer is a Claude Code skill for building visual brand identities, from logos to brand guidelines. It responds to requests for palettes, typography systems, and social media templates. CX Codex +1 242installs tailwind A Tailwind CSS v4 skill for themes, components, dark mode, container queries, v3 migrations, shadcn/ui, and build troubleshooting. CX Codex +1 233installs vitest-testing vitest-testing adds Vitest patterns and best practices to Claude Code. Helps write reliable unit, component, and hook tests without typical async mistakes. CX Codex +1 226installs content-humanizer content-humanizer rewrites model-written drafts so they read like a person wrote them: sentence rhythm, tone, and the hedging that gives AI text away. CX Codex +1 225installs tanstack-form This skill guides TanStack Form v1 usage in React, covering state, validation, and submission. Use it for complex forms and changing field lists. CX Codex +1 222installs knowledge-graph-builder The knowledge-graph-builder skill guides knowledge-graph design, graph database choice, and graph-plus-vector retrieval. Use it for Graph RAG, entity resolution, and fact checks. CX Codex +1 222installs pino-logging Set up structured Pino logging in Node.js, including request context, sensitive-field redaction, transports, and framework integrations. CX Codex +1 217installs database-security database-security audits the data layer of Supabase, Postgres and Convex apps: RLS coverage, policy holes, service-role leaks, audit logging. Useful before a release or after an incident. CX Codex +1 208installs

Project sponsors

Companies that keep this analytics open