OpenParable
Skip to content
← Back to skills

Atmos Project Layout

Development
atmos-project-layout

Atmos Project Layout is an Agent Skill for development published in the cloudposse/atmos repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Atmos project layout: base_path, relative path resolution, root stacks/components/workflows/schemas directories, atmos.d modular config, and repository path conventions

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cloudposse/atmos/blob/HEAD/agent-skills/skills/atmos-project-layout/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atmos-project-layout, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

NeedLoad
Config discovery, merge order, import of root configatmos-config
Stack discovery, stack imports, stack namingatmos-stacks
Component type directories and component metadataatmos-components
Terraform backend and command-specific path behavioratmos-terraform
Workflow file discoveryatmos-workflows
Schema directories and validation pathsatmos-schemas, atmos-validation
Profiles path and activationatmos-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.