Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/zod

Implement version-aware Zod schemas and runtime parsing; not diff review or library selection.

---
name: zod
description: Implement version-aware Zod schemas and runtime parsing; not diff review or library selection.
---

# Zod Schemas and Parsing

Implement validation at a named trust boundary using the project's installed Zod version. Selected boundary-validation, inference, and migration topics adapt [secondsky's Zod skill](https://github.com/secondsky/claude-skills/blob/88378361314f558fb719aec0af9fd898ab36f0b2/plugins/zod/skills/zod/SKILL.md), under the bundled `LICENSE.secondsky-claude-skills`. Examples here are rewritten and do not inherit its claim that every upstream example is verified.

## Route precisely

- Use to create or change Zod schemas, parsing, coercion, transforms, refinements, codecs, or validation-error mapping for API payloads, forms, files, configuration, or external responses.
- Use `code-review` for a read-only diff review, `vet-dependency` to decide whether to adopt Zod, `api-and-interface-design` for an undecided public contract, and `typescript-type-design` for pure type-level mechanisms.
- Use `deprecation-and-migration` for a live contract rollout. A Zod upgrade can change accepted data, defaults, serialized output, and clients; a library upgrade alone does not authorize those changes.

## Establish version and boundary

Read repository instructions, package/lock metadata, actual import path (`zod`, `zod/v4`, `zod/mini`, or core), compiler support, and local parsing/error conventions. Read installed declarations or version-matched official docs before using APIs. Do not infer a major version from the presence of `z.codec`: it arrived after the first Zod 4 release. Zod 4 documents TypeScript 5.5+ and strict checking; verify the supported combination instead of silently changing tsconfig.

Name the untrusted source, required input, normalized output, unknown-key policy, error consumer, and side-effect boundary. Validation is not authorization, output encoding, rate limiting, or proof that a database operation is safe. Preserve the project's manager, framework, and error contract; do not install a library or replace a validation system without task scope.

## Implement the contract

1. Define small schemas and derive types from them. Distinguish `z.input<typeof S>` from `z.output<typeof S>` for coercion, defaults, transforms, and codecs; `z.infer` describes output. Consume the parsed `data`, not the original input narrowed by a success-only predicate.
2. Choose strip, reject, or preserve behavior for unknown keys deliberately. Defaults, optional, nullable, absent, and explicit `undefined` have different contracts. Check empty form strings and boolean/number coercion rather than assuming conversion validates the intended business meaning.
3. Choose `.safeParse()` for an explicit success/error branch, or `.parse()` when the caller deliberately handles `ZodError` or startup must fail. Existing correct exception handling is not a defect. Use async parsing for async refinements/transforms and await it.
4. Handle JSON syntax errors before schema parsing. `safeParse` does not catch an exception thrown while evaluating its argument, nor arbitrary exceptions from user transforms/refinements. Make expected callback failures validation issues using the installed API; keep unexpected infrastructure errors distinguishable.
5. Compose schemas without weakening constraints or accidentally overwriting fields. Check discriminated variants independently. For codecs, verify encode and decode separately, including invalid input and unsupported reverse transforms; use version-supported safe/async variants as needed. Do not promise that a generic transform is reversible.
6. Map errors to the existing API/UI contract. Preserve useful paths and codes without leaking raw input, secrets, or internal messages. Framework error adapters and form resolvers must match the installed versions.

Read [references/parsing-contracts.md](references/parsing-contracts.md) for executable examples and [references/version-boundaries.md](references/version-boundaries.md) only for version or migration questions. Do not load unrelated framework integrations or require an ESLint plugin to use this workflow.

## Verify and report

Run the configured type check separately from runtime validation tests. Include valid data, malformed JSON, invalid shape, unknown keys, coercion, defaults, transformed output versus original input, and async failure only where relevant. For codecs, include both directions and round-trip behavior under stated normalization. A schema's inferred type alone proves none of these runtime behaviors.

For a claimed fix, identify the old behavior rejected by the test and use a proportionate isolated negative control. Record exact package/compiler versions, selected cases, skips, and missing checks. Return changed schemas and consumers, input/output and error contracts, observed evidence, and rollout limits. Never claim all Zod 4 minor releases share every documented API.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall