zod

SKILL.md

Zod Best Practices

Comprehensive schema validation guide for Zod in TypeScript applications. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

Writing new Zod schemas

Choosing between parse() and safeParse()

Implementing type inference with z.infer

Handling validation errors for user feedback

Composing complex object schemas

Using refinements and transforms

Optimizing bundle size and validation performance

Reviewing Zod code for best practices

Rule Categories by Priority

Priority
Category
Impact
Prefix

1
Schema Definition
CRITICAL
schema-

2
Parsing & Validation
CRITICAL
parse-

3
Type Inference
HIGH
type-

4
Error Handling
HIGH
error-

5
Object Schemas
MEDIUM-HIGH
object-

6
Schema Composition
MEDIUM
compose-

7
Refinements & Transforms
MEDIUM
refine-

8
Performance & Bundle
LOW-MEDIUM
perf-

Quick Reference

1. Schema Definition (CRITICAL)

schema-use-primitives-correctly - Use correct primitive schemas for each type

schema-use-unknown-not-any - Use z.unknown() instead of z.any() for type safety

schema-avoid-optional-abuse - Avoid overusing optional fields

schema-string-validations - Apply string validations at schema definition

schema-use-enums - Use enums for fixed string values

schema-coercion-for-form-data - Use coercion for form and query data

2. Parsing & Validation (CRITICAL)

parse-use-safeparse - Use safeParse() for user input

parse-async-for-async-refinements - Use parseAsync for async refinements

parse-handle-all-issues - Handle all validation issues not just first

parse-validate-early - Validate at system boundaries

parse-avoid-double-validation - Avoid validating same data twice

parse-never-trust-json - Never trust JSON.parse output

3. Type Inference (HIGH)

type-use-z-infer - Use z.infer instead of manual types

type-input-vs-output - Distinguish z.input from z.infer for transforms

type-export-schemas-and-types - Export both schemas and inferred types

type-branded-types - Use branded types for domain safety

type-enable-strict-mode - Enable TypeScript strict mode

4. Error Handling (HIGH)

error-custom-messages - Provide custom error messages

error-use-flatten - Use flatten() for form error display

error-path-for-nested - Use issue.path for nested error location

error-i18n - Implement internationalized error messages

error-avoid-throwing-in-refine - Return false instead of throwing in refine

5. Object Schemas (MEDIUM-HIGH)

object-strict-vs-strip - Choose strict() vs strip() for unknown keys

object-partial-for-updates - Use partial() for update schemas

object-pick-omit - Use pick() and omit() for schema variants

object-extend-for-composition - Use extend() for adding fields

object-optional-vs-nullable - Distinguish optional() from nullable()

object-discriminated-unions - Use discriminated unions for type narrowing

6. Schema Composition (MEDIUM)

compose-shared-schemas - Extract shared schemas into reusable modules

compose-intersection - Use intersection() for type combinations

compose-lazy-recursive - Use z.lazy() for recursive schemas

compose-preprocess - Use preprocess() for data normalization

compose-pipe - Use pipe() for multi-stage validation

7. Refinements & Transforms (MEDIUM)

refine-vs-superrefine - Choose refine() vs superRefine() correctly

refine-transform-coerce - Distinguish transform() from refine() and coerce()

refine-add-path - Add path to refinement errors

refine-defaults - Use default() for optional fields with defaults

refine-catch - Use catch() for fault-tolerant parsing

8. Performance & Bundle (LOW-MEDIUM)

perf-cache-schemas - Cache schema instances

perf-zod-mini - Use Zod Mini for bundle-sensitive applications

perf-avoid-dynamic-creation - Avoid dynamic schema creation in hot paths

perf-lazy-loading - Lazy load large schemas

perf-arrays - Optimize large array validation

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels

Rule template - Template for adding new rules

Individual rules: references/{prefix}-{slug}.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Related Skills

For React Hook Form integration, see react-hook-form skill

For API client generation, see orval skill

Sources

Zod Official Documentation

Zod v4 Release Notes

Zod GitHub Repository

Zod Mini

Total TypeScript Zod Tutorial