Agent skill

Configuration

This skill should be used when the user asks about "Effect Config", "environment variables", "configuration management", "Config.string", "Config.number", "ConfigProvider", "Config.nested", "Config.withDefault", "Config.redacted", "sensitive values", "config validation", "loading config from JSON", "config schema", or needs to understand how Effect handles application configuration.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/configuration-andrueandersoncs-claude-skill-effect-

SKILL.md

Configuration in Effect

Overview

Effect provides type-safe configuration loading with:

  • Automatic environment variable reading
  • Validation and type conversion
  • Default values and composition
  • Sensitive value handling
  • Multiple config sources (env, JSON, custom)

Basic Configuration Types

typescript
import { Config, Effect } from "effect"

const host = Config.string("HOST")

const port = Config.number("PORT")

const debug = Config.boolean("DEBUG")

const maxConnections = Config.integer("MAX_CONNECTIONS")

Using Config in Effects

typescript
const program = Effect.gen(function* () {
  const host = yield* Config.string("DATABASE_HOST")
  const port = yield* Config.number("DATABASE_PORT")

  return { host, port }
})

// Runs and reads from environment
await Effect.runPromise(program)

Default Values

typescript
const port = Config.number("PORT").pipe(
  Config.withDefault(3000)
)

const debug = Config.boolean("DEBUG").pipe(
  Config.withDefault(false)
)

Optional Configuration

typescript
const apiKey = Config.string("API_KEY").pipe(
  Config.option
)
// Type: Effect<Option<string>>

Combining Configurations

Using Config.all

typescript
const dbConfig = Config.all({
  host: Config.string("DB_HOST"),
  port: Config.number("DB_PORT"),
  database: Config.string("DB_NAME"),
  maxConnections: Config.number("DB_MAX_CONN").pipe(
    Config.withDefault(10)
  )
})

const program = Effect.gen(function* () {
  const config = yield* dbConfig
  // config: { host: string, port: number, database: string, maxConnections: number }
})

Nested Configurations

typescript
const dbConfig = Config.nested("DB")(
  Config.all({
    host: Config.string("HOST"),      // Reads DB_HOST
    port: Config.number("PORT"),      // Reads DB_PORT
    name: Config.string("NAME")       // Reads DB_NAME
  })
)

Config with Schema Validation

Use Effect Schema for complex validation:

typescript
import { Config, Schema } from "effect"

const PortSchema = Schema.Number.pipe(
  Schema.int(),
  Schema.between(1, 65535)
)

const port = Config.number("PORT").pipe(
  Config.mapOrFail((n) =>
    Schema.decodeUnknownEither(PortSchema)(n).pipe(
      Either.mapLeft((e) => ConfigError.InvalidData([], `Invalid port: ${n}`))
    )
  )
)

Handling Sensitive Values

Config.redacted

Prevents accidental logging of sensitive values:

typescript
const apiKey = Config.redacted("API_KEY")
// Type: Effect<Redacted<string>>

const program = Effect.gen(function* () {
  const key = yield* apiKey

  // Safe to log - shows "<redacted>"
  yield* Effect.log(`Key: ${key}`)

  // Get actual value when needed
  const actual = Redacted.value(key)
})

Secret Type

typescript
const dbPassword = Config.secret("DB_PASSWORD")
// Type: Effect<Secret.Secret>

const program = Effect.gen(function* () {
  const password = yield* dbPassword
  const value = Secret.value(password) // Get actual string
})

Config Operators

Transforming Values

typescript
const upperHost = Config.string("HOST").pipe(
  Config.map((s) => s.toUpperCase())
)

const port = Config.string("PORT").pipe(
  Config.mapOrFail((s) => {
    const n = parseInt(s)
    return isNaN(n)
      ? Either.left(ConfigError.InvalidData([], "Not a number"))
      : Either.right(n)
  })
)

Fallback Values

typescript
const host = Config.string("PRIMARY_HOST").pipe(
  Config.orElse(() => Config.string("SECONDARY_HOST")),
  Config.orElse(() => Config.succeed("localhost"))
)

Custom Config Providers

From Environment (Default)

typescript
const program = Effect.gen(function* () {
  const host = yield* Config.string("HOST")
})

From JSON/Object

typescript
import { ConfigProvider, Layer } from "effect"

const config = {
  host: "localhost",
  port: "3000",
  database: {
    host: "db.example.com",
    port: "5432"
  }
}

const JsonConfigProvider = ConfigProvider.fromJson(config)

const program = Effect.gen(function* () {
  const host = yield* Config.string("host")
  const dbHost = yield* Config.nested("database")(Config.string("host"))
})

const runnable = program.pipe(
  Effect.provide(Layer.setConfigProvider(JsonConfigProvider))
)

From Map

typescript
const MapProvider = ConfigProvider.fromMap(
  new Map([
    ["HOST", "localhost"],
    ["PORT", "3000"]
  ])
)

Combining Providers

typescript
const CombinedProvider = ConfigProvider.orElse(
  ConfigProvider.fromEnv(),
  () => ConfigProvider.fromJson(defaultConfig)
)

Config in Layers

typescript
const AppConfigLive = Layer.effect(
  AppConfig,
  Effect.gen(function* () {
    const host = yield* Config.string("HOST")
    const port = yield* Config.number("PORT")
    const debug = yield* Config.boolean("DEBUG").pipe(Config.withDefault(false))

    return { host, port, debug }
  })
)

Testing Configuration

Mock Config Provider

typescript
const TestConfigProvider = ConfigProvider.fromMap(
  new Map([
    ["HOST", "test-host"],
    ["PORT", "9999"]
  ])
)

const testProgram = program.pipe(
  Effect.provide(Layer.setConfigProvider(TestConfigProvider))
)

Config.succeed for Hardcoded

typescript
const testConfig = Config.succeed({
  host: "localhost",
  port: 3000
})

Error Handling

Config failures produce ConfigError:

typescript
const program = Effect.gen(function* () {
  const host = yield* Config.string("REQUIRED_HOST")
}).pipe(
  Effect.catchTag("ConfigError", (error) =>
    Effect.fail(new StartupError({ cause: error }))
  )
)

Complete Example

typescript
import { Config, Effect, Layer, Schema } from "effect"

// Define config shape
const AppConfig = Config.all({
  server: Config.nested("SERVER")(
    Config.all({
      host: Config.string("HOST").pipe(Config.withDefault("0.0.0.0")),
      port: Config.number("PORT").pipe(Config.withDefault(3000))
    })
  ),
  database: Config.nested("DATABASE")(
    Config.all({
      url: Config.redacted("URL"),
      maxConnections: Config.number("MAX_CONN").pipe(Config.withDefault(10))
    })
  ),
  features: Config.all({
    debug: Config.boolean("DEBUG").pipe(Config.withDefault(false)),
    metrics: Config.boolean("METRICS_ENABLED").pipe(Config.withDefault(true))
  })
})

// Use in application
const program = Effect.gen(function* () {
  const config = yield* AppConfig
  yield* Effect.log(`Starting server on ${config.server.host}:${config.server.port}`)
})

Best Practices

  1. Use Config.withDefault for optional values - Avoid runtime errors
  2. Use Config.redacted for secrets - Prevents accidental logging
  3. Use Config.nested for structure - Organizes related config
  4. Validate with Schema - Catch invalid config early
  5. Test with mock providers - Deterministic tests

Additional Resources

For comprehensive configuration documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

  • "Configuration" for full API reference
  • "ConfigProvider" for custom providers
  • "Handling Sensitive Values" for security

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results