agentleFS
Sign inStart free
tazo90tazo90/next-openapi-gen/.agents/skills/zod/SKILL.md

zod

Skill193 starsChanged 3 months agoMITView on GitHub

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).

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read individual reference files for detailed explanations and code examples:

    line 106

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
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

PriorityCategoryImpactPrefix
1Schema DefinitionCRITICALschema-
2Parsing & ValidationCRITICALparse-
3Type InferenceHIGHtype-
4Error HandlingHIGHerror-
5Object SchemasMEDIUM-HIGHobject-
6Schema CompositionMEDIUMcompose-
7Refinements & TransformsMEDIUMrefine-
8Performance & BundleLOW-MEDIUMperf-

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free