# 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](https://agentskills.io) 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](/ai/skills). **File:** `atmos.yaml` ```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](https://agentskills.io). 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: ```text +-- 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. :::tip 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 ``` :::info 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](https://agentskills.io). 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: ```markdown --- 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](/cli/configuration/ai/tools) for the full list of available tools. **Allowed Tools** control which tools a skill can access. An empty list means all tools are available: ```yaml allowed_tools: [] # Skill can use any tool ``` **Restricted Tools** require user confirmation before execution: ```yaml 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: **File:** `atmos.yaml` ```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: **File:** `atmos.yaml` ```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" :::tip 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 :::tip Use Existing Skills First Atmos ships with [official skills](/cli/commands/ai/skill) 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 **File:** `atmos.yaml` ```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 **File:** `atmos.yaml` ```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 **File:** `atmos.yaml` ```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 - [AI Chat Command](/cli/commands/ai/chat) - Interactive AI chat interface - [AI Configuration](/cli/configuration/ai) - Configure AI providers and settings - [Claude Code Integration](/ai/claude-code-integration) - Use Atmos with Claude Code - [Tools Configuration](/cli/configuration/ai/tools) - Tool execution and permissions - [`atmos ai skill`](/cli/commands/ai/skill) - Install and share community skills ## Declarative sources Declare shared skill sources alongside existing inline skills. A source entry cannot contain inline prompt or tool fields. ```yaml 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 ``` | Field | Meaning | Default | |---|---|---| | `source` | Git repository or local directory | Required | | `ref` | Branch, tag, commit, or `!version dependency` | Repository default branch | | `kind` | `auto`, `marketplace`, or `skills` | `auto` | | `subpath` | Relative directory inside the source | Repository root | | `plugins` | Marketplace plugin names | All plugins | | `include` / `exclude` | Skill-name glob patterns; exclusion wins | All skills | | `clients` | `claude-code`, `vscode`, `gemini` | Detect installed clients | | `scope` | `project` or `user` | `project` | 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: ```shell 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: ```shell 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. ```shell 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.