Skip to main content

AI Skills

The ai.skills section defines custom AI skills with specialized system prompts, tool permissions, and behavior for different tasks. Skills follow the Agent Skills open standard governed by the Linux Foundation's Agentic AI Foundation (AAIF).

Experimental

Configuration​

Set the default skill and optionally define custom skills in atmos.yaml. Marketplace skills (installed via atmos ai skill install) are available automatically -- browse the full set in the Agent Skills Directory.

atmos.yaml
ai:
  default_skill: "atmos-stacks"    # Use a marketplace skill as default
  skills:
    # Custom skills are defined here (marketplace skills are loaded automatically)
    security-reviewer:
      display_name: "Security Reviewer"
      description: "Reviews infrastructure for security best practices"
      category: "security"
      system_prompt: |
        You are a security expert for Atmos infrastructure.
        Focus on access controls, encryption, and network security.
      allowed_tools:
        - atmos_describe_component
        - atmos_list_stacks
        - atmos_validate_stacks
        - read_stack_file
        - read_component_file
      restricted_tools: []

Skill Schema​

Each skill in the skills map supports the following settings:

display_name
Required. Human-readable name shown in the skill selector (Ctrl+A) and session metadata.
description
Required. Brief description of what the skill does. Shown in the skill selector below the display name.
system_prompt
Required. System prompt that defines the AI's behavior, expertise, and response style for this skill. Use YAML multi-line (|) for longer prompts.
allowed_tools
List of tools available when this skill is active (default: []). An empty list means all tools are available. Use specific tool names to restrict access.
restricted_tools
List of tools that require user confirmation before execution, even if they are in allowed_tools (default: []).
category
Skill category for organization: general, analysis, refactor, security, validation, or optimization.

Global Skill Settings​

default_skill
Default skill to activate when starting a new chat session (default: general). Set at the ai level.

Installing Skills​

Atmos AI skills are distributed via the Agent Skills marketplace. The official Atmos skills package contains 25 specialized skills covering all aspects of infrastructure orchestration.

shell
# Install all official Atmos skills from the marketplace
atmos ai skill install cloudposse/atmos

# Install with a specific version
atmos ai skill install cloudposse/atmos@v1.200.0

# List installed skills
atmos ai skill list

# Uninstall a specific skill
atmos ai skill uninstall atmos-terraform

# Force reinstall all skills
atmos ai skill install cloudposse/atmos --force

If no skills are installed, atmos ai chat works with a minimal fallback prompt and displays a hint to install specialized skills.

Using Skills in the TUI​

Press Ctrl+A in the chat interface to open the skill selector:

+-- Switch AI Skill -------------------------------------------+
|                                                              |
| Up/Down: Navigate | Enter: Select | Esc/q: Cancel            |
|                                                              |
|   atmos-components                                           |
|      Component management and best practices                 |
|                                                              |
|   atmos-config                                               |
|      Configuration validation and management                 |
|                                                              |
| > atmos-terraform (current)                                  |
|      Terraform operations and troubleshooting                |
|                                                              |
|   atmos-security                                             |
|      Security review of infrastructure configs               |
|                                                              |
|   atmos-stacks                                               |
|      Stack analysis and dependency management                |
|                                                              |
+--------------------------------------------------------------+

Use Up/Down or j/k to navigate, Enter to select, Esc or q to cancel.

Skill Display Order

Skills are displayed in alphabetical order for consistent, predictable navigation.

Skill Persistence in Sessions​

Skills are persisted per session. When you resume a named session, the previously selected skill is automatically restored:

shell
atmos ai chat --session vpc-review
# Press Ctrl+A, select atmos-validation
# ... do work ...

# Next time, skill is automatically restored
atmos ai chat --session vpc-review
Skill Availability

If you resume a session that was using a custom skill that is no longer available in your configuration, Atmos falls back to the default skill and logs a debug message.

Skill Prompt System​

Atmos AI uses SKILL.md files that follow the Agent Skills open standard. Skills are installed from the marketplace and stored in ~/.atmos/skills/.

Architecture​

The system separates Go code (pkg/ai/skills/) for infrastructure and tool execution from SKILL.md files (~/.atmos/skills/) for skill metadata and instructions. This means you can update skills without recompiling Atmos by running atmos ai skill install --force, and the community can contribute improvements via pull requests.

Skills are loaded when the TUI initializes, and each skill's instructions are only sent to the model when that skill is active (progressive disclosure for token efficiency).

SKILL.md File Structure​

Each skill follows this format with YAML frontmatter and Markdown body:

---
name: skill-name
display_name: "Skill Display Name"
description: Brief description of the skill
version: 1.0.0
category: general|analysis|refactor|security|validation|optimization
icon: wrench

tools:
  allowed:
    - tool_name1
    - tool_name2
  restricted:
    - tool_name3
---

# Skill: [Name]

## Role
Brief description of the skill's purpose and expertise

## Your Expertise
- Domain knowledge areas
- Key competencies

## Instructions
Step-by-step guidance for the skill to follow

## Best Practices
Extracted from Atmos documentation

## Example Workflows
Common usage patterns and examples

## Response Style
How the skill should format and present information

Tool Safety Patterns​

See Tools Configuration for the full list of available tools.

Allowed Tools control which tools a skill can access. An empty list means all tools are available:

allowed_tools: []  # Skill can use any tool

Restricted Tools require user confirmation before execution:

allowed_tools:
  - read_file
  - edit_file
restricted_tools:
  - edit_file  # User must confirm before skill can edit files

Read-Only Skill -- omit write and execute tools entirely:

atmos.yaml
skills:
  config-auditor:
    display_name: "Config Auditor"
    description: "Read-only configuration audit"
    system_prompt: "You audit stack configurations for issues..."
    allowed_tools:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
      - read_file
      - search_files
    # No write/execute tools = read-only

Write with confirmation -- allow edits but require approval:

atmos.yaml
skills:
  component-refactorer:
    display_name: "Component Refactorer"
    description: "Refactors Terraform components"
    system_prompt: "You are an expert in Terraform component refactoring..."
    allowed_tools:
      - read_file
      - edit_file
      - list_component_files
      - execute_bash_command
    restricted_tools:
      - edit_file             # Require confirmation before editing
      - execute_bash_command  # Require confirmation before executing

Performance Tips​

Choosing the right skill improves both response quality and speed:

General
Exploration, cross-domain questions, quick queries. Example: "What is Atmos?", "Help me debug this error"
atmos-stacks
Stack configs, imports, inheritance, dependencies. Example: "Analyze dependencies between prod stacks"
atmos-components
Terraform module design, component refactoring. Example: "Refactor VPC component to use Terraform 1.5 syntax"
atmos-validation
OPA/Rego policies, JSON Schema, config errors. Example: "Write an OPA policy to enforce tagging standards"
atmos-terraform
Plan/apply orchestration, workspace management. Example: "Debug this Terraform state lock issue"
atmos-config
YAML structure, configuration merging. Example: "Validate my atmos.yaml configuration"
atmos-security
Security review, access controls. Example: "Audit my infrastructure for security issues"
Switch skills as your workflow progresses

Start with atmos-stacks to understand architecture, switch to atmos-components to make improvements, then use atmos-validation to verify changes. Specialized skills make fewer tool calls and produce more accurate results than using the general skill for everything.

For custom skills, keep them focused on a single domain. A skill that tries to handle security, cost, compliance, and refactoring at once will perform poorly at all of them. Give skills only the tools they need -- a smaller tool set means the AI makes better tool choices.

Marketplace Skills​

Atmos includes 25 marketplace skills covering all aspects of infrastructure orchestration:

atmos-terraform
Terraform orchestration: plan/apply/deploy, workspace management, backend config, varfile generation, authentication.
atmos-stacks
Stack configuration: imports, inheritance, deep merging, locals, vars, settings, metadata, overrides.
atmos-components
Component architecture: Terraform root modules, abstract components, inheritance, versioning, mixins, catalog patterns.
atmos-ansible
Ansible playbook execution, variable passing, inventory management.
atmos-asciicast
Terminal cast recording workflows, fixtures, validation, and website cast assets.
atmos-aws-security
AWS security findings, component mapping, remediation, and compliance reports.
atmos-validation
Policy validation: OPA/Rego policies, JSON Schema, schema manifests.
atmos-schemas
JSON Schema for stack manifests, IDE auto-completion, and validation.
atmos-config
Project configuration: atmos.yaml structure, all sections, discovery, merging, base paths, settings.
atmos-auth
Authentication and identity management: providers (SSO/SAML/OIDC/GCP), identities, keyring, identity chaining.
atmos-templates
Go templates: Sprig/Gomplate functions, atmos.Component, atmos.GomplateDatasource, atmos.Store.
atmos-yaml-functions
YAML functions: !terraform.state, !terraform.output, !store, !env, !exec, !include, !template.
atmos-vendoring
Component vendoring: vendor.yaml manifests, pulling from Git/S3/HTTP/OCI/Terraform Registry.
atmos-workflows
Workflow automation: multi-step workflows, Go template support, cross-component orchestration.
atmos-custom-commands
Project-specific CLI commands in atmos.yaml with arguments, flags, env maps, and shared steps.
atmos-steps
Shared step DSL for workflows, custom commands, hooks, and cast recordings.
atmos-hooks
Lifecycle hooks for Terraform operations, store publishing, scanners, git, commands, and steps.
atmos-gitops
CI/CD: GitHub Actions, Spacelift, Atlantis, atmos describe affected for change detection.
atmos-helmfile
Helmfile sync/apply/destroy/diff, Kubernetes deployments, and EKS integration.
atmos-packer
Packer init/build/validate, machine image building, and template management.
atmos-stores
Store backends and cross-component data sharing.
atmos-toolchain
CLI tool version management via Aqua registries, .tool-versions, install, and exec.
atmos-introspection
describe/list commands for querying stacks, components, dependencies, and change impact.
atmos-devcontainer
Devcontainer management: start/stop/shell/exec, Docker/Podman, and identity integration.
atmos-design-patterns
Design patterns: stack organization, component catalogs, inheritance, configuration composition.

Custom Skill Examples​

Use Existing Skills First

Atmos ships with 57 official skills covering Terraform, stacks, components, validation, auth, templates, and more. Check the catalog before creating custom skills - most common use cases are already covered. Reserve custom skills for organization-specific needs that official skills don't address.

Custom skills complement marketplace skills for organization-specific needs.

Cost Optimizer​

atmos.yaml
ai:
  skills:
    cost-optimizer:
      display_name: "Cost Optimizer"
      description: "Analyzes infrastructure for cost savings opportunities"
      category: "analysis"
      system_prompt: |
        You are a cost optimization expert for Atmos infrastructure.

        FOCUS AREAS:
        - Identify overprovisioned resources
        - Suggest rightsizing opportunities
        - Find unused or idle resources
        - Recommend reserved instances

        Always use tools to gather data before making recommendations.
      allowed_tools:
        - atmos_describe_component
        - atmos_list_stacks
        - read_stack_file
        - read_component_file
        - read_file
        - search_files
      restricted_tools: []

Compliance Auditor​

atmos.yaml
ai:
  skills:
    compliance-auditor:
      display_name: "Compliance Auditor"
      description: "Ensures infrastructure meets regulatory requirements"
      category: "security"
      system_prompt: |
        You are a compliance expert for regulated industries (HIPAA, SOC2, PCI-DSS).

        COMPLIANCE CHECKS:
        - Data encryption (at rest and in transit)
        - Audit logging and monitoring
        - Access controls and authentication
        - Data residency requirements

        REPORTING:
        - Categorize by compliance framework
        - Cite specific requirements (e.g., "HIPAA 164.312(a)(2)(iv)")
        - Mark findings as Pass/Fail/Partial
        - Provide remediation with compliance rationale
      allowed_tools:
        - atmos_describe_component
        - atmos_list_stacks
        - atmos_validate_stacks
        - read_stack_file
        - read_component_file
        - read_file
        - search_files

Migration Assistant​

atmos.yaml
ai:
  skills:
    migration-assistant:
      display_name: "Migration Assistant"
      description: "Assists with infrastructure migrations and upgrades"
      category: "refactor"
      system_prompt: |
        You are an infrastructure migration expert.

        MIGRATION FOCUS:
        - Upgrade deprecated Terraform syntax
        - Update provider version constraints
        - Modernize component configurations
        - Ensure backward compatibility

        Make incremental changes and verify at each step.
      allowed_tools:
        - read_file
        - edit_file
        - list_component_files
        - read_component_file
        - search_files
        - execute_bash_command
      restricted_tools:
        - edit_file             # Require confirmation before editing
        - execute_bash_command  # Require confirmation before executing

Related Documentation​

Declarative sources​

Declare shared skill sources alongside existing inline skills. A source entry cannot contain inline prompt or tool fields.

version:
  track: prod
  dependencies:
    atmos-skills:
      datasource: github-tags
      package: cloudposse/atmos
      desired: v1.229.0

ai:
  skills:
    cloudposse:
      source: cloudposse/atmos
      kind: marketplace
      plugins: [atmos]
      ref: !version atmos-skills
      clients: [claude-code]
      scope: project
FieldMeaningDefault
sourceGit repository or local directoryRequired
refBranch, tag, commit, or !version dependencyRepository default branch
kindauto, marketplace, or skillsauto
subpathRelative directory inside the sourceRepository root
pluginsMarketplace plugin namesAll plugins
include / excludeSkill-name glob patterns; exclusion winsAll skills
clientsclaude-code, vscode, geminiDetect installed clients
scopeproject or userproject

Marketplace discovery supports relative plugin directories and github, url, and git-subdir Git plugin sources. Only skills are installed. Hooks, agents, MCP configuration, plugin dependencies, npm, archive, and command sources are not installed. Unsupported selected source types fail.

Declare, then install​

Configuration commands do not install or remove files:

atmos ai skill add cloudposse/atmos --name cloudposse
atmos ai skill set cloudposse plugins '[atmos]'
atmos ai skill set cloudposse ref '!version atmos-skills'
atmos version track lock prod
atmos ai skill sync --track prod

The add, set, and remove commands preserve YAML comments, tags, and existing file permissions. Partial declarations are validated against the merged configuration. Use --dry-run to preview edits. If a declaration occurs in multiple configuration layers, removal requires a single explicit --config file and reports declarations remaining in other layers.

Locks and updates​

Commit skills.lock.yaml and the configured version lock. The skills lock pins every contributing Git repository, including external marketplace plugins, and records skill content digests. Unchanged declarations reuse locked commits. Local directory sources use content digests; run update to accept changed local content. A project-root source: . excludes generated .atmos state, skills.lock.yaml, and installation destinations owned by this project from its snapshot. Authored files, including other hidden files, remain part of the source digest.

For managed refs, advance the version track before synchronizing:

atmos version track update prod
atmos ai skill sync --track prod
atmos ai skill sync --track prod --frozen
atmos ai skill sync --track prod --check

The --frozen flag requires matching locks and may install missing copies. The --check flag checks offline without writing and fails for missing, stale, modified, or obsolete installations. The --dry-run flag previews reconciliation without persistent changes; it may download sources to temporary directories. A skill update never independently advances a !version dependency.

Ownership and removal​

Project copies and machine-local records live under .atmos/skills/; ignore that directory in Git. Different projects can install different revisions. User installations are shared, and another project cannot take over their ownership. Atmos loads project skills before user skills and inline entries, reporting shadowed names.

atmos ai skill remove cloudposse
atmos ai skill sync                  # Reports retained obsolete copies
atmos ai skill sync --prune          # Removes unchanged obsolete owned copies
atmos ai skill uninstall demo --source cloudposse --client claude-code

An explicit client selection limits changes to those destinations. Canonical content remains while other client copies need it. Ad-hoc installations are excluded from declarative pruning.

Modified owned files require --force before replacement or deletion. Existing unowned directories are never overwritten, even with force. Source symlinks, path escapes, and destination symlinks are rejected. Failed replacements roll back; if recovery is interrupted, use atmos ai skill sync --recover from the owning project before retrying. Existing legacy user skills remain readable; legacy client copies are not assumed to be owned.