What is effect-config-schema?

This Claude skill enables robust configuration management and schema validation using the Effect ecosystem. It streamlines the process of defining type-safe configurations, validating external inputs like API request bodies, and performing complex data transformations. By leveraging the Effect library's patterns, it ensures architectural consistency, early error detection, and enhanced type safety in TypeScript projects.

When should I use effect-config-schema?

effect-config-schema is useful in the following scenarios: • Type-Safe Input Validation: Automatically decode and validate incoming JSON payloads or API request parameters against strictly typed schemas to prevent runtime errors. • Environment Configuration: Load and validate application settings from environment variables with support for nesting, default values, and automatic type conversion. • Data Transformation and Branding: Seamlessly convert raw input data into domain-specific types, such as transforming ISO strings into Date objects or applying branded types for specialized identifiers. • Complex Credential Resolution: Implement conditional logic to select between different authentication methods (e.g., AWS Access Keys vs. IAM Roles) based on available configuration state.

name	effect-config-schema
description	Config loading and Schema validation/transform. Use when defining configuration or validating inputs.
allowed-tools	Read, Grep, Glob, Edit, Write, mcp__effect-docs__effect_docs_search

Config & Schema

When to use

Validating request bodies, params, or external inputs
Loading environment configuration with types

Config (example)

import { Config } from "effect"

const Server = Config.nested("SERVER")(Config.all({
  host: Config.string("HOST"),
  port: Config.number("PORT")
}))

Schema Validate

import { Schema as S } from "effect"

const User = S.Struct({ id: S.Number, name: S.String })
const decodeUser = (u: unknown) => S.decodeUnknown(User)(u)

Transform

const IsoDate = S.String // then transform to Date in pipeline where needed

Real-world snippet: Layer selecting AWS credentials via Config options

class AwsCredentials extends Effect.Service<AwsCredentials>()("AwsCredentials", {
  effect: Effect.gen(function* () {
    const accessKeys = yield* Config.option(
      Config.all([Config.string("CAP_AWS_ACCESS_KEY"), Config.string("CAP_AWS_SECRET_KEY")])
    )
    const vercelAwsRole = yield* Config.option(Config.string("VERCEL_AWS_ROLE_ARN"))

    const credentials = yield* Effect.gen(function* () {
      if (Option.isSome(vercelAwsRole)) return awsCredentialsProvider({ roleArn: vercelAwsRole.value })
      if (Option.isSome(accessKeys)) {
        const [accessKeyId, secretAccessKey] = accessKeys.value
        return { accessKeyId, secretAccessKey }
      }
      return fromContainerMetadata()
    })

    return { credentials }
  })
})

Guidance

Prefer schemas close to boundaries; keep core logic typed
For branded types (Email, PositiveInt), use transform/brand helpers
Validate early, map to domain errors in one place

Pitfalls

Accepting unknown into core → always decode first
Large ad-hoc validation code → centralize in Schema

Cross-links

HTTP & Routing for endpoint validation
Foundations for operator style

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/. Always search the actual implementation before writing Effect code.

Key Source Files

Config: docs/effect-source/effect/src/Config.ts
Schema: docs/effect-source/schema/src/Schema.ts

Example Searches

# Find Config patterns and options
grep -F "Config.string" docs/effect-source/effect/src/Config.ts
grep -F "Config.number" docs/effect-source/effect/src/Config.ts
grep -F "Config.option" docs/effect-source/effect/src/Config.ts

# Study Schema validation
grep -F "Struct" docs/effect-source/schema/src/Schema.ts
grep -F "decodeUnknown" docs/effect-source/schema/src/Schema.ts

# Find Schema transforms
grep -rF "transform" docs/effect-source/schema/src/
grep -rF "brand" docs/effect-source/schema/src/

# Look at Config test examples
grep -F "Config." docs/effect-source/effect/test/Config.test.ts

Workflow

Identify the Config or Schema API you need
Search docs/effect-source/effect/src/Config.ts or docs/effect-source/schema/src/Schema.ts
Study the types and validation patterns
Look at test files for usage examples
Write your code based on real implementations

Real source code > documentation > assumptions

References

Agent Skills overview: https://www.anthropic.com/news/skills
Skills guide: https://docs.claude.com/en/docs/claude-code/skills

effect-config-schema

When & Why to Use This Skill

Use Cases