Atmos Root Configuration
Use this skill for the root mechanics of atmos.yaml: how Atmos finds config files, merges them,
resolves project-relative paths, imports modular config, and routes section-specific work to the
right skill. Do not use this skill as a catchall for every atmos.yaml section.
Configuration Discovery
Atmos searches for atmos.yaml in this order:
--config CLI flag or ATMOS_CLI_CONFIG_PATH.- Active profile selected by
--profile or ATMOS_PROFILE.
- Current working directory.
- Git repository root.
- Parent directory walk.
- Home directory.
- System directory.
When multiple configuration files apply, Atmos deep-merges them. More specific sources override
broader defaults.
Root Layout
Use base_path for the project root that relative paths resolve from. Keep the root config small
and point subsystem paths at their owning directories:
base_path: ""
stacks:
base_path: stacks
included_paths:
- "**/*"
excluded_paths:
- "**/_defaults.yaml"
- "catalog/**/*"
name_template: "{{ .vars.stage }}"
components:
terraform:
base_path: components/terraform
workflows:
base_path: stacks/workflows
For deeper path/layout guidance, load atmos-project-layout.
Modular Imports
Use import to split root config into focused files:
import:
- atmos.d/stacks.yaml
- atmos.d/components.yaml
- atmos.d/auth.yaml
- atmos.d/toolchain.yaml
Imported files are deep-merged into the active configuration. Keep imported files aligned with the
subsystem they configure and load the subsystem skill before changing that section.
Routing
| Need |
Load |
| Root discovery, merge order, imports, minimal bootstrap |
stay in atmos-config |
Project paths, base_path, path conventions, relative path resolution |
atmos-project-layout |
Profiles, --profile, ATMOS_PROFILE, profile directory merge behavior |
atmos-profiles |
Global CLI behavior, settings, logs, errors, env, docs, metadata |
atmos-settings |
| Stack manifests, inheritance, stack imports, vars, locals, stack naming |
atmos-stacks |
| Component structure, abstract components, metadata, component inheritance |
atmos-components |
| Terraform/OpenTofu commands, backend defaults, Terraform component settings |
atmos-terraform |
| Helmfile, Packer, or Ansible component behavior |
atmos-helmfile, atmos-packer, atmos-ansible |
| Workflows section and workflow syntax |
atmos-workflows |
| Custom commands and aliases |
atmos-custom-commands |
| Auth providers, identities, keyring, cloud auth conventions |
atmos-auth |
| Stores and store-backed YAML functions |
atmos-stores |
Tool versions, dependencies.tools, registries, shell/PATH integration |
atmos-toolchain |
| Native CI, GitHub Actions, Atlantis, matrices, CI outputs |
atmos-ci |
| Schemas and validation policy configuration |
atmos-schemas, atmos-validation |
| Templates and YAML functions |
atmos-templates, atmos-yaml-functions |
| Vendoring external components |
atmos-vendoring |
| Introspection commands and querying resolved config |
atmos-introspection |
For a compact map of top-level sections, read references/sections-reference.md.
Guardrails
- Keep
atmos-config examples minimal; detailed subsystem examples belong in their narrower skills.
- Before editing a subsystem section, load the owning skill from the routing table.
- Prefer
atmos describe config or atmos describe component when verifying merge or path behavior.
1---2name: atmos-config3description: Atmos root configuration: atmos.yaml discovery, precedence, deep merging, base_path, imports, minimal bootstrap, and routing to narrower Atmos skills4---56# Atmos Root Configuration78Use this skill for the root mechanics of `atmos.yaml`: how Atmos finds config files, merges them,9resolves project-relative paths, imports modular config, and routes section-specific work to the10right skill. Do not use this skill as a catchall for every `atmos.yaml` section.1112## Configuration Discovery1314Atmos searches for `atmos.yaml` in this order:15161. `--config` CLI flag or `ATMOS_CLI_CONFIG_PATH`.172. Active profile selected by `--profile` or `ATMOS_PROFILE`.183. Current working directory.194. Git repository root.205. Parent directory walk.216. Home directory.227. System directory.2324When multiple configuration files apply, Atmos deep-merges them. More specific sources override25broader defaults.2627## Root Layout2829Use `base_path` for the project root that relative paths resolve from. Keep the root config small30and point subsystem paths at their owning directories:3132```yaml33base_path: ""3435stacks:36 base_path: stacks37 included_paths:38 - "**/*"39 excluded_paths:40 - "**/_defaults.yaml"41 - "catalog/**/*"42 name_template: "{{ .vars.stage }}"4344components:45 terraform:46 base_path: components/terraform4748workflows:49 base_path: stacks/workflows50```5152For deeper path/layout guidance, load [atmos-project-layout](../atmos-project-layout/SKILL.md).5354## Modular Imports5556Use `import` to split root config into focused files:5758```yaml59import:60 - atmos.d/stacks.yaml61 - atmos.d/components.yaml62 - atmos.d/auth.yaml63 - atmos.d/toolchain.yaml64```6566Imported files are deep-merged into the active configuration. Keep imported files aligned with the67subsystem they configure and load the subsystem skill before changing that section.6869## Routing7071| Need | Load |72|---|---|73| Root discovery, merge order, imports, minimal bootstrap | stay in `atmos-config` |74| Project paths, `base_path`, path conventions, relative path resolution | `atmos-project-layout` |75| Profiles, `--profile`, `ATMOS_PROFILE`, profile directory merge behavior | `atmos-profiles` |76| Global CLI behavior, `settings`, `logs`, `errors`, `env`, `docs`, `metadata` | `atmos-settings` |77| Stack manifests, inheritance, stack imports, vars, locals, stack naming | `atmos-stacks` |78| Component structure, abstract components, metadata, component inheritance | `atmos-components` |79| Terraform/OpenTofu commands, backend defaults, Terraform component settings | `atmos-terraform` |80| Helmfile, Packer, or Ansible component behavior | `atmos-helmfile`, `atmos-packer`, `atmos-ansible` |81| Workflows section and workflow syntax | `atmos-workflows` |82| Custom commands and aliases | `atmos-custom-commands` |83| Auth providers, identities, keyring, cloud auth conventions | `atmos-auth` |84| Stores and store-backed YAML functions | `atmos-stores` |85| Tool versions, `dependencies.tools`, registries, shell/PATH integration | `atmos-toolchain` |86| Native CI, GitHub Actions, Atlantis, matrices, CI outputs | `atmos-ci` |87| Schemas and validation policy configuration | `atmos-schemas`, `atmos-validation` |88| Templates and YAML functions | `atmos-templates`, `atmos-yaml-functions` |89| Vendoring external components | `atmos-vendoring` |90| Introspection commands and querying resolved config | `atmos-introspection` |9192For a compact map of top-level sections, read [references/sections-reference.md](references/sections-reference.md).9394## Guardrails9596- Keep `atmos-config` examples minimal; detailed subsystem examples belong in their narrower skills.97- Before editing a subsystem section, load the owning skill from the routing table.98- Prefer `atmos describe config` or `atmos describe component` when verifying merge or path behavior.
cloudposse