# Configuration

Where a configuration value belongs, app config schema, agent-native.config.ts, or an...

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill configuration -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill configuration -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill configuration -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill configuration -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

Where a configuration value belongs, app config schema, agent-native.config.ts, or an environment variable, and how the layers resolve. Use before adding an env var, a configure*/set* function, a plugin option, or a register* function, and when deciding whether something is config or a registry.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Configuration

Core had 301 distinct environment variables and only 48 of them were secrets.
The other 253 are product decisions that landed in `process.env` because at the
call site that needed them, nothing else was reachable. This skill exists so the
next value does not do the same thing.

## The rule

**Consumer code never reads `process.env`.** Exactly four resolvers do:

| Resolver | Covers |
| --- | --- |
| The app config env layer (`app-config/env-layer.ts`) | product behavior, via a declared `.meta({ env })` alias |
| `resolveDeployEnvironment()` | platform facts, `NODE_ENV`, `NETLIFY`, `AWS_*` |
| `readDeployCredentialEnv()` | secrets, as the deployment layer inside scoped resolution |
| `getAmbientUserEmail()` / `getAmbientOrgId()` | CLI identity when there is no request context |

The bottom three are not configuration: platform variables are facts nobody
sets in an app, credentials resolve per user or org, and ambient identity exists
only for CLI runs. Everything else is a field in the schema.

This is the credential rule ("one resolver per key, and every runtime path goes
through it") applied to all configuration, with a schema lookup replacing the
grep.

## Where a value goes

| Value | Where |
| --- | --- |
| Server behavior, closures, per-tenant resolvers, anything not for a browser | `defineAppConfig()` |
| Client-visible data | `agent-native.config.ts` |
| A deployment override of a server value | an `env` alias on the schema field |
| A secret value | the vault, via `resolveCredential`, see the `secrets` skill |
| Something a user changes at runtime in the UI | the settings store, not config |

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/configuration/SKILL.md