Environment Setup

Environment Configuration

Use this skill as the repository's narrower application-config and `.env` compatibility skill.

The job is to make app configuration clear and safe across environments:

• decide what belongs in env vars,
• structure .env files and precedence rules,
• validate required config,
• separate public/private values,
• reduce config drift between local, CI, staging, and production,
• make secret handoff explicit.

Read references/env-patterns.md and references/scope-boundaries.md before unusual cases or when deciding whether the real need belongs in system-environment-setup.

If the user mainly needs:

• toolchains, local services, Docker Compose, devcontainers, or onboarding → route to system-environment-setup
• deployment or CI secret wiring → pair with deployment-automation
• security architecture or policy → pair with security-best-practices

When to use this skill

• Design .env.example, .env.local, or per-environment config structure
• Explain env precedence and which values should or should not be committed
• Validate required env vars with typed/runtime checks
• Separate server-only vs client-exposed env values
• Reduce drift between local, CI, staging, and production config
• Clean up a repo where env files, secret docs, and runtime expectations disagree
• Decide when env vars are enough and when secret-manager injection is needed

When not to use this skill

• The main task is making the full repo runnable across machines → use system-environment-setup
• The main task is local service orchestration, Docker, or devcontainers → use system-environment-setup
• The main task is deployment automation or production rollout → use deployment-automation
• The main task is broader security review rather than config organization → pair with security-best-practices

Instructions

Step 1: Classify the config problem

Normalize the request into this intake first:

env_config_intake:
  primary_goal: env-structure | validation | secret-handoff | public-private-split | drift-cleanup | framework-rules | unknown
  app_shape: backend | frontend | fullstack | monorepo | unknown
  current_storage: env-files | framework-config | secret-manager | mixed | unknown
  drift_surface:
    - missing-required-vars
    - duplicate-env-files
    - CI-local-mismatch
    - public-private-leak-risk
    - undocumented-secret-source
    - framework-prefix-confusion
    - unclear
  confidence: high | medium | low

Step 2: Choose one primary mode

Pick exactly one mode for the run:

1. env-file-structure

• Use when the main need is file layout, naming, and precedence.

2. env-validation

• Use when missing or malformed values are causing runtime/build pain.

3. secret-handoff-boundary

• Use when .env files are colliding with secret-manager or credential-delivery concerns.

4. framework-config-rules

• Use when the main problem is framework-specific env behavior (public/private prefixes, build-time vs runtime exposure, etc.).

5. drift-cleanup

• Use when env templates, docs, CI vars, and actual runtime expectations disagree.

Step 3: Apply config rules

• Keep deploy-specific values out of source code and commit only safe templates.
• Separate committed templates from developer-local values.
• Make public/client-exposed env vars visually distinct from server-only values.
• Prefer typed validation when the app is large enough for env drift to be expensive.
• Record the source of secrets: local file, secret manager, CI variable, or cloud platform.
• Route outward when the actual blocker is machine setup, Docker, or local services rather than config design.

Step 4: Build the config brief

Return this exact structure:

# Environment Config Brief

## Recommended mode
- Mode: env-file-structure | env-validation | secret-handoff-boundary | framework-config-rules | drift-cleanup
- Why this mode fits: ...

## Current config surface
- App shape: ...
- Config sources: ...
- Main drift or risk: ...
- Confidence: high | medium | low

## Recommended config layout
1. ...
2. ...
3. ...

## Example files / checks

...

## Why this layout is safer
- ...
- ...

## Watch-outs
- ...
- ...

## Adjacent handoff
- Use `system-environment-setup` for ...
- Use `deployment-automation` for ...
- Use `security-best-practices` for ...

Step 5: Use mode-specific guidance

For env-file-structure

• Define the committed template files first.
• Call out local-only overrides and ignored files explicitly.
• Make precedence easy to explain.

For env-validation

• Choose a schema/validation layer appropriate for the stack.
• Fail fast with clear missing-variable messages.
• Keep validation close to app startup.

For secret-handoff-boundary

• Name which values are safe in templates and which must come from a secret source.
• Document how a developer obtains sensitive values.
• Avoid pretending secret-manager adoption removes the need for local conventions.

For framework-config-rules

• Explain public/private env prefixes and build-time/runtime behavior.
• Call out framework-specific exposure risks.

For drift-cleanup

• Compare templates, runtime code, CI vars, and docs.
• Remove duplicate or stale env file conventions.
• Make one source of truth obvious.

Step 6: Keep boundaries sharp

Before finalizing:

• Do not turn this into a Docker/devcontainer tutorial.
• Do not bury public/private env exposure risk.
• Do not assume .env files are enough for all secret workflows.
• Do not keep this as a peer duplicate of system-environment-setup; route broader setup work outward.

Examples

Example 1: Env template cleanup

Input: "Help me structure .env.example and .env.local so new devs stop guessing values." Output: chooses env-file-structure, defines committed templates vs local overrides, and keeps the scope at app config.

Example 2: Validation hardening

Input: "We keep forgetting env vars until runtime." Output: chooses env-validation, recommends typed validation, and shows how to fail fast.

Example 3: Framework split

Input: "Which env vars can be exposed to the frontend and which must stay server-only?" Output: chooses framework-config-rules, explains the client/server split, and avoids broad setup drift.

Best practices

1. Treat this as the app-config layer, not the whole-machine setup skill. 2. Make secret sources explicit rather than implied. 3. Prefer committed templates plus local-only overrides. 4. Add validation once env drift becomes expensive. 5. Route broader runnable-repo work to system-environment-setup.

References

• Environment patterns
• Scope boundaries
• Twelve-Factor config
• Next.js env guide
• T3 Env intro

Environment Configuration Patterns

Recommended baseline layering

1. Committed template — .env.example or equivalent, containing safe placeholder keys and comments. 2. Local-only override — .env.local or ignored machine-specific values. 3. Framework/runtime rules — documented public/private prefixes and build/runtime behavior. 4. Validation layer — schema or startup checks for required values. 5. Secret source note — where sensitive values actually come from.

Questions to answer explicitly

• Which env files are committed?
• Which files are ignored?
• Which variables are safe to expose to the client?
• Which values come from secret managers or cloud platforms?
• What fails fast if a required value is missing?

Common drift smells

• README documents variables that the app no longer reads.
• CI uses variables that never appear in templates.
• .env.production is committed even though real prod values come from the platform.
• Frontend/public env names are mixed with server-only secrets.
• The team cannot explain precedence in one short paragraph.

Environment Setup Boundaries

Use environment-setup when the real question is application configuration.

It owns:

• .env template structure
• env precedence and local-only overrides
• typed env validation
• public/private env variable boundaries
• secret handoff documentation
• config drift cleanup across local, CI, staging, and production

Route away when the need changes

Runnable local machines and containers

Use system-environment-setup when the real question is:

• how do I get the repo running on a fresh machine?
• should we use Docker Compose or devcontainers?
• how do we standardize toolchains and local services?
• why does onboarding still fail even with env templates?

Deployment automation

Use deployment-automation when the real question is:

• how are values injected in CI/CD or production?
• how do we wire cloud deployments, previews, or hosted environments?

Security architecture

Use security-best-practices when the real question is:

• should we adopt a secret manager?
• how should secret access and rotation work?
• what security posture should config handling follow?

Core rule

environment-setup owns the app-config layer. It should not masquerade as the whole runnable-environment playbook.