Atmos Asciicast

Atmos Asciicast Development Skill

Use this Claude skill when creating or updating committed .cast recordings inside the Atmos repository.

This is an internal Atmos development skill. It is intentionally separate from distributed Agent Skills. Do not symlink it to agent-skills, copy internal website assumptions into Agent Skills, or treat Claude skills and Agent Skills as synchronized artifacts.

Intent

Atmos casts are product demos, regression evidence, and documentation examples at the same time. They should show users that Atmos workflows are simple to follow and that the feature being demonstrated works in a realistic project.

• Tell a small story a user can follow: inspect context, run the Atmos command, show the result.
• Prefer Atmos-native commands and workflow features over clever shell expressions.
• Keep recorded steps light. A visible step should usually be one command with one teaching purpose.
• Use hidden setup, cleanup, and fixture preparation only to make the recorded story deterministic.
• Treat each cast as evidence for a feature: include the command output that proves the behavior, then validate the committed .cast.

Defaults

• Use shared cast defaults when available instead of repeating terminal settings on each cast step:

  defaults:
    cast: !include cast-defaults.yaml .cast
    simulate: !include cast-defaults.yaml .simulate
  env: !include cast-defaults.yaml .env.recording

• Keep common recording settings in cast-defaults.yaml under cast, simulate, and env (env.command for command setup, env.recording for the recorded process).

• Write curated Atmos docs casts under website/static/casts/...; they are served from /casts/....

• Use type: cast with mode: steps for deterministic command demos that need exit-code propagation.

• Use mode: session only when the demo must show typed input, prompts, key presses, or terminal timing.

• Keep ad hoc local recordings in the XDG cache via --cast; do not commit cache recordings.

Fixture Policy

• Use deterministic Atmos demo fixtures under demo/casts.
• Do not reuse product examples or test fixtures just to make a docs cast easier.
• Keep demo output stable: no local absolute paths, hostnames, real account IDs, secrets, random IDs, or live timestamps.

Workflow Patterns

• Put repeatable setup in atmos casts setup using type: workdir for fixture copies and a local GOBIN for the Atmos binary.
• Keep pre-recording clean steps simple; they remove stale .cast files before recording and do not need failure cleanup semantics.
• Put cleanup-after-recording steps after the type: cast step and use when: always when they restore secrets, stop services, or remove Terraform state.
• Leave validation steps success-only so validation runs only after recording and required cleanup complete successfully.
• Use output: none for noisy setup, reset, and cleanup commands that should not be part of the story.
• Prefer type: cast mode: steps with nested type: shell steps for command demos; add type: simulate steps only when typed prompts make a longer story easier to follow.
• Use type: toast for short recorded status narration instead of shell printf output.
• Keep large shell scripts out of recorded casts. If unavoidable, hide them in setup/cleanup and explain the user-facing result with lightweight Atmos commands in the recording.
• Use path-based custom command names for demo casts, for example casts generate demo fixtures native-terraform plan, and publish fixture casts under /casts/demo/fixtures/....