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
npx skills add oakoss/agent-skills --skill zod-validation -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/zod-validation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/zod-validation/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill zod-validation -a codex2Manually: put the files in place
.agents/skills/zod-validation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill zod-validation -a cursor2Manually: put the files in place
.cursor/skills/zod-validation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/zod-validation2Manually: put the files in place
.github/skills/zod-validation/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill zod-validation -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/zod-validationManually: put the files in place
.devin/skills/zod-validation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill zod-validation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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