Atmos Scaffold

Atmos Scaffold

Use this skill for generating boilerplate (components, configs, directory structures) from templates via atmos scaffold generate, for authoring new templates (scaffold.yaml), and for updating previously-generated output from a changed template via --update.

For bootstrapping a brand-new Atmos project from the built-in template catalog, load atmos-init instead — it shares this exact engine but has its own command surface and built-in template list.

Quick Shape

apiVersion: atmos/v1
kind: AtmosScaffoldConfig
metadata:
  name: terraform-component
  description: Standard Terraform component structure
spec:
  fields:
    - name: component_name
      label: Name of the component
      type: input
      required: true

atmos scaffold generate terraform-component ./components/terraform/vpc
atmos scaffold list
atmos scaffold validate ./components/terraform/vpc/scaffold.yaml

atmos scaffold ships experimental — behavior may change between releases.

Creating a Template

A template is a directory containing scaffold.yaml (the questionnaire and optional conditional-generation/hooks config) plus the files to generate. Files are auto-discovered by walking the template directory — there is no files: manifest listing every file (spec.files: exists only for the optional conditional-generation overlay, see below).

Mark a file as a Go template (rendered with the collected answers) either by:

• Naming it with a .tmpl extension, or
• Adding an atmos:template magic comment in the first 10 lines, in the comment style matching the file type: # atmos:template (shell/YAML/Python), // atmos:template (Go/JS/C++), /* atmos:template */ (C-style block), <!-- atmos:template --> (HTML/XML/Markdown)

Template sources: embedded (built into the Atmos binary), custom (declared under scaffold.templates in atmos.yaml), or catalog/remote (git/https/s3/oci — advertised as stubs, fetched on selection). An OCI source (oci://ghcr.io/org/template:v1) is pulled via the same pkg/oci client atmos vendor pull reuses (load atmos-vendoring for the URL syntax and auth precedence). --ref only applies to git sources; OCI/S3/local sources address a version through the source string itself.

Form Fields

spec.fields is an ordered questionnaire; fields prompt in the order declared.

Common field keys: name (required, used as the template variable — access via {{ .Config.<name> }}), label, description, required, default, options (select/multiselect), placeholder (input), validation.pattern/message (regex, input fields only).

Dynamic and label/value options: (select/multiselect)

options: accepts a plain string list, a list of {label, value} objects, a dot-path into an earlier answer, or a Go-template expression:

spec:
  fields:
    - name: envs
      type: multiselect
      options:                       # {label, value} objects — value is required, label optional
        - label: Development
          value: dev
        - label: Production
          value: prod
    - name: default_env
      type: select
      options: answers.envs          # dot-path: only the environments actually picked above
    - name: csv_owners
      type: input
      default: "platform-team,security-team"
    - name: primary_owner
      type: select
      options: '{{ splitList "," answers.csv_owners }}'   # Go-template expression

The dot-path and template-expression forms resolve correctly once the referenced earlier field has been answered — interactively (fields prompt one at a time, so a later field is only ever shown after the ones before it) or headlessly against --set/--defaults — the same answers.-prefix convention spec.files[].matrix axes use. A dot-path may also point at a spec.values preset or a --set-supplied value never declared as a field at all; there's no field-declaration-order check at load time, so a forward/self/typo'd reference degrades gracefully at runtime instead of failing to load. When a dot-path (not a template expression) sources from a field using {label, value} pairs, those labels are recovered for the filtered subset of values present in the answer — only values ever flow into answers/templates, never labels. Full details: references/scaffold-yaml-schema.md.

Conditional prompts (when:)

A field can declare when: to be shown only if a condition on earlier-declared fields' answers holds true:

spec:
  fields:
    - name: enable_monitoring
      type: confirm
      default: false
    - name: alert_email
      type: input
      when: "answers.enable_monitoring == true"   # only asked if confirmed above

when: accepts a predicate keyword (always, never, ci, local), a CEL string, or a list (implicit all). Reference collected answers via the answers map — e.g. "'dev' in answers.environments" for a multiselect, "answers.x == true" for a confirm (a bare answers.x is not valid CEL here — it's typed dyn, not bool; compare explicitly). Use CEL's &&/||/! for compound conditions — the {all:/any:/not:} map form is not accepted for scaffold when: (see references/scaffold-yaml-schema.md for why). A when: can only see fields declared before it in the list.

Full field/validation reference: references/scaffold-yaml-schema.md.

Conditional File Generation

spec.files: is an optional overlay gating specific auto-discovered files, keyed by their path in the template tree. Files not listed always generate.

spec:
  files:
    - path: stacks/deploy/dev.yaml
      when: "'dev' in answers.environments"
    - path: stacks/deploy/staging.yaml
      when: "'staging' in answers.environments"

This is static gating over a fixed, enumerable set of files the template author already created — one file stays one file. For generating a variable number of files (one per selected value, or one per resolved combination of several axes), see spec.files[].matrix below.

path: can also be a glob (doublestar syntax: *, ?, [...], ** for any depth, {a,b}), matching every discovered file under it, so one entry gates or skips an entire directory recursively instead of listing every file it contains:

spec:
  files:
    - path: "docs/legacy/**"
      when: "answers.include_legacy_docs == true"   # gates the whole directory at once

Always use forward slashes in the pattern — a backslash is normalized to / regardless of authoring OS. A malformed pattern (unclosed [/{) fails scaffold load and atmos scaffold validate immediately, not silently at generation time. When more than one entry's path: matches the same file, the last declared entry wins (.gitignore/CODEOWNERS precedence — write broad patterns first, specific overrides after).

This is distinct from the older path-templating trick: if a file's path itself is a Go template that renders to "", "false", "null", or "<no value>", the engine skips it too (ShouldSkipFile). Prefer declarative when: for new templates — it's evaluated before any rendering and doesn't require crafting a path template.