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.

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 21+ 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 21 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-validation
Policy validation: OPA/Rego policies, JSON Schema, schema manifests.
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-gitops
CI/CD: GitHub Actions, Spacelift, Atlantis, atmos describe affected for change detection.
atmos-design-patterns
Design patterns: stack organization, component catalogs, inheritance, configuration composition.

Custom Skill Examples​

Use Existing Skills First

Atmos ships with 21+ marketplace skills covering Terraform, stacks, components, validation, auth, templates, and more. Check the marketplace before creating custom skills — most common use cases are already covered. Reserve custom skills for organization-specific needs that marketplace 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