Atmos Project Layout

Use this skill for repository layout, root paths, and how atmos.yaml paths resolve.

Root Paths

base_path sets the root for most relative project paths. Keep it explicit when a repository does not use the current directory as the Atmos root.

base_path: ""

stacks:
  base_path: stacks

components:
  terraform:
    base_path: components/terraform

workflows:
  base_path: stacks/workflows

schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa

Conventional Layout

.
  atmos.yaml
  atmos.d/
    stacks.yaml
    components.yaml
    auth.yaml
  components/
    terraform/
    helmfile/
    packer/
    ansible/
  stacks/
    catalog/
    workflows/
    orgs/
    schemas/

Use atmos.d/ for modular root config when atmos.yaml gets too large. Use stack imports for stack manifest inheritance and catalog composition; do not confuse root config imports with stack imports.

Path Rules

Root base_path controls how project paths resolve.
Subsystem base_path values are normally relative to the root base_path.
Workflow --file values are relative to workflows.base_path.
Schema paths are relative to their schema base path unless an absolute path is used.
Stack import paths are a stack-manifest concern; load atmos-stacks for stack inheritance details.

Routing

Need	Load
Config discovery, merge order, `import` of root config	`atmos-config`
Stack discovery, stack imports, stack naming	`atmos-stacks`
Component type directories and component metadata	`atmos-components`
Terraform backend and command-specific path behavior	`atmos-terraform`
Workflow file discovery	`atmos-workflows`
Schema directories and validation paths	`atmos-schemas`, `atmos-validation`
Profiles path and activation	`atmos-profiles`

Guardrails

Do not force the canonical components/terraform layout during migrations; point base_path and component paths at the user's existing repository when that is safer.
Prefer a small root atmos.yaml plus focused atmos.d/*.yaml files for large projects.
Verify layout assumptions with atmos describe config before generating large changes.

SKILL.md