home / skills / busirocket / agents-skills / busirocket-validation

busirocket-validation skill

safe

This skill enforces consistent input and API data validation using Zod schemas and guard helpers, ensuring safe boundary checks.

npx playbooks add skill busirocket/agents-skills --skill busirocket-validation

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

2.2 KB

---
name: busirocket-validation
description:
  Validation strategy using Zod for schemas and guard helpers for runtime
  checks. Use when validating API responses, request inputs, or external data at
  boundaries.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# Validation (Zod + Guards)

Consistent validation at boundaries: Zod for complex schemas, small guards for
simple runtime checks.

## When to Use

Use this skill when:

- Validating API responses or external data in services
- Validating request/input shapes at boundaries (e.g. route handlers, SDK)
- Adding or refactoring `utils/validation/` helpers
- Defining Zod schemas alongside types in `types/<area>/`

## Non-Negotiables (MUST)

- **Services**: validate API/external data with Zod schemas (e.g.
  `.safeParse()`).
- **Utils**: keep small coercion/guard helpers under `utils/validation/` (one
  function per file).
- **Types**: Zod schemas can live in `types/<area>/`; infer types with
  `z.infer<typeof Schema>`.
- Prefer `unknown` inputs at boundaries + explicit narrowing.
- No inline validation logic inside components/hooks.

## Rules

### Boundaries & Placement

- `validation-boundaries` - Where validation lives (services, utils, types)

### Zod Schemas (Complex Validation)

- `validation-zod-schemas` - Using Zod for complex validation with
  `.safeParse()`
- `validation-zod-types` - Inferring types from Zod schemas with `z.infer`

### Guard Helpers (Simple Runtime Checks)

- `validation-guard-helpers` - Creating simple guard functions with type
  predicates
- `validation-guard-examples` - Recommended guard helpers (isRecord,
  isNonEmptyString, etc.)

### Anti-Patterns

- `validation-no-inline` - No inline validation logic in components/hooks

## Related Skills

- `busirocket-nextjs` - Validation in route handlers
- `busirocket-core-conventions` - File boundaries and structure

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/validation-boundaries.md
rules/validation-zod-schemas.md
rules/validation-guard-helpers.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

Overview

This skill defines a validation strategy using Zod schemas for complex shapes and small guard helpers for simple runtime checks. It enforces validation at service and utility boundaries, encourages inferring types from schemas, and avoids inline validation inside UI components or hooks. The goal is consistent, safe handling of external and boundary data.

How this skill works

Use Zod schemas to describe and validate complex API responses and request payloads, calling .safeParse() at service boundaries to ensure runtime safety. Keep lightweight guard functions (type predicates) for trivial checks like non-empty strings or plain objects, each implemented as a single utility function. Prefer accepting unknown at boundaries and explicitly narrow types after validation, with Zod schemas living alongside inferred TypeScript types.

When to use it

Validating API responses or external data in backend services and SDKs
Validating request shapes at route handlers, RPC endpoints, or server actions
Adding or refactoring utils/validation helpers for small runtime checks
Defining Zod schemas and inferring types in types/<area>/ for shared domains
Any boundary where untrusted input enters your system

Best practices

Validate at boundaries (services, route handlers, SDK entry points) not inside components
Use Zod for complex schemas and .safeParse() to handle errors explicitly
Keep guard helpers small and focused—one function per file under utils/validation/
Accept unknown at inputs and narrow types immediately after validation
Infer TypeScript types with z.infer<typeof Schema> and keep schemas near domain types

Example use cases

Server handler validates incoming JSON with a Zod schema before processing
Service layer validates third-party API responses with .safeParse() and returns typed results
Small guard isNonEmptyString used in a utility to guard optional query parameters
Create types/users/UserSchema in types/users/ and infer User from it for shared use
Refactor inline checks in a component into utils/validation/isRecord to centralize logic

FAQ

When should I use a guard helper vs Zod?

Use guard helpers for trivial checks (non-empty string, plain object) to keep runtime overhead minimal. Use Zod for structured, nested, or validated coercions and when you need detailed error reporting.

Where do I place schemas and guards?

Place complex Zod schemas in types/<area>/ alongside inferred types. Put small guard helpers in utils/validation/, one function per file for clarity and discoverability.