zod
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
- Installs
- 7.1K
- Last 24h
- +21
- Trending rank
- #5636
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill zod- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads zod automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 typeschema-use-unknown-not-any- Use z.unknown() instead of z.any() for type safetyschema-avoid-optional-abuse- Avoid overusing optional fieldsschema-string-validations- Apply string validations at schema definitionschema-use-enums- Use enums for fixed string valuesschema-coercion-for-form-data- Use coercion for form and query data
2. Parsing & Validation (CRITICAL)
parse-use-safeparse- Use safeParse() for user inputparse-async-for-async-refinements- Use parseAsync for async refinementsparse-handle-all-issues- Handle all validation issues not just firstparse-validate-early- Validate at system boundariesparse-avoid-double-validation- Avoid validating same data twiceparse-never-trust-json- Never trust JSON.parse output
3. Type Inference (HIGH)
type-use-z-infer- Use z.infer instead of manual typestype-input-vs-output- Distinguish z.input from z.infer for transformstype-export-schemas-and-types- Export both schemas and inferred typestype-branded-types- Use branded types for domain safetytype-enable-strict-mode- Enable TypeScript strict mode
4. Error Handling (HIGH)
error-custom-messages- Provide custom error messageserror-use-flatten- Use flatten() for form error displayerror-path-for-nested- Use issue.path for nested error locationerror-i18n- Implement internationalized error messageserror-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 keysobject-partial-for-updates- Use partial() for update schemasobject-pick-omit- Use pick() and omit() for schema variantsobject-extend-for-composition- Use extend() for adding fieldsobject-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 modulescompose-intersection- Use intersection() for type combinationscompose-lazy-recursive- Use z.lazy() for recursive schemascompose-preprocess- Use preprocess() for data normalizationcompose-pipe- Use pipe() for multi-stage validation
7. Refinements & Transforms (MEDIUM)
refine-vs-superrefine- Choose refine() vs superRefine() correctlyrefine-transform-coerce- Distinguish transform() from refine() and coerce()refine-add-path- Add path to refinement errorsrefine-defaults- Use default() for optional fields with defaultsrefine-catch- Use catch() for fault-tolerant parsing
8. Performance & Bundle (LOW-MEDIUM)
perf-cache-schemas- Cache schema instancesperf-zod-mini- Use Zod Mini for bundle-sensitive applicationsperf-avoid-dynamic-creation- Avoid dynamic schema creation in hot pathsperf-lazy-loading- Lazy load large schemasperf-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-formskill - For API client generation, see
orvalskill
Sources
FAQ
What does the zod skill do?
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
How do I install zod?
Run npx skills add https://github.com/pproenca/dot-skills --skill zod in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/zod/ (personal) or .claude/skills/zod/ (project).
Which AI agents can use zod?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is zod safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains zod?
It is published by pproenca in pproenca/dot-skills. It has 7,056 recorded installs.
More from pproenca/dot-skills
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
typescript
pproenca/dot-skills
TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.