Atmos Project Layout
Developmentatmos-project-layoutAtmos 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
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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_pathcontrols how project paths resolve. - Subsystem
base_pathvalues are normally relative to the rootbase_path. - Workflow
--filevalues are relative toworkflows.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-stacksfor 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/terraformlayout during migrations; pointbase_pathand component paths at the user's existing repository when that is safer. - Prefer a small root
atmos.yamlplus focusedatmos.d/*.yamlfiles for large projects. - Verify layout assumptions with
atmos describe configbefore generating large changes.