atmos ai skill

Use this command to manage community and custom AI skills. Install skills from GitHub repositories, list installed skills, and remove skills you no longer need.

Experimental

Configure AI Skills

Declare skill sources, select clients, and pin revisions in your Atmos configuration.

Configuration Reference

See also: Agent Skills Directory to browse every skill | AI Skills Configuration for configuring skills in atmos.yaml

atmos ai skill --help

Description

Skills are specialized AI assistants that provide expert knowledge for specific domains. They follow the Agent Skills open standard and can be installed from GitHub repositories.

The atmos ai skill command lets you:

• Install official skills by name (offline) or community skills from GitHub
• List the full catalog of available skills alongside what's installed
• Update installed skills from bundled content, local sources, or Git repositories
• Reconcile declared sources with exact revision locks and owned client copies
• Remove skills you no longer need

Global --skill Flag

You can use installed skills with any Atmos command via the global --skill flag (requires --ai). The skill's system prompt is sent to the AI provider for domain-specific analysis.

atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform

See Global Flags for details.

What Are Agent Skills?

Atmos ships 57 official agent skills that give AI coding assistants deep, accurate knowledge of Atmos conventions, stack configuration, Terraform orchestration, authentication, validation, and more -- browse them all in the Agent Skills Directory. They live in the agent-skills/ folder at the root of the Atmos repository and work across Claude Code, Gemini CLI, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, and more.

Each official skill is a self-contained package with:

• SKILL.md -- The primary instruction file (under 500 lines) with YAML frontmatter metadata
• references/ -- Deeper reference files that the AI loads only when the task requires them

Skills use a three-tier progressive disclosure pattern so AI context windows stay focused:

1. Router (AGENTS.md) -- A lightweight index that maps user tasks to the right skill
2. Skill (SKILL.md) -- Domain-specific instructions, patterns, and examples
3. References (references/*.md) -- Detailed specifications, schemas, and command references

The AI loads the router first, identifies which skill applies, loads that skill, and only pulls in reference files when deep detail is needed. You do not invoke skills manually -- your AI tool activates the right skill automatically based on your question. For step-by-step client setup, see Configure AI Assistants.

Official SKILL.md Format

SKILL.md

---
name: atmos-stacks
description: "Stack configuration: imports, inheritance, deep merging, locals, vars, settings, metadata, overrides, atmos.yaml setup"
metadata:
  copyright: Copyright Cloud Posse, LLC 2026
  version: "1.0.0"
  category: core-config
references:
  - references/import-patterns.md
  - references/inheritance-deep-merge.md
---

# Atmos Stacks

Instructions for the AI assistant...

name

Unique identifier for the skill (must match the directory name).

description

Human-readable summary of what the skill teaches.

metadata.category

Groups the skill in the Agent Skills Directory (e.g. orchestrators, security, ci-automation).

references

Optional list of deeper reference files the AI should load when more detail is needed.

Skills build on two open standards: AGENTS.md for project-level AI instructions, and Agent Skills (SKILL.md) for packaging AI capabilities with instructions, references, and assets.

Contributing an Official Skill

Official skills are maintained in the Atmos repository under agent-skills/. To contribute one:

1. Follow the existing folder structure: agent-skills/skills/<skill-name>/SKILL.md
2. Keep the primary SKILL.md under 500 lines for optimal context usage
3. Place detailed reference material in references/ subdirectories
4. Update AGENTS.md to include your skill in the routing table
5. Use YAML frontmatter with name, description, metadata (containing copyright, version, and category), and optionally references fields

New skills appear automatically in the Agent Skills Directory -- no separate doc update needed. See the Atmos Contributing Guide for general contribution guidelines.

Usage

atmos ai skill <subcommand> [flags]

Subcommands

atmos ai skill install

Install a skill by its bundled name (offline), from a local or Git source, or from a declared source label.

The official Atmos skills are embedded in the binary, so installing one by its bare name (for example atmos-terraform) works fully offline — no network or Git clone required. Run atmos ai skill list to see every available skill. You can also install any skill from a GitHub repository. Omit <source> entirely to install every bundled skill at once.

Atmos keeps a canonical copy in .atmos/skills/content/<name> and distributes additional copies into detected clients' directories (.github/skills/ for VS Code/Copilot, .claude/skills/ for Claude Code, .gemini/skills/ for Gemini). Declared client selections take precedence over detection; --client/--all-clients override the selection for this invocation. --path adds a manual destination alongside the canonical copy and skips client distribution.

Use --scope user (or --global) for user-level canonical and client copies (~/.atmos/skills/content/, ~/.claude/skills/, ~/.copilot/skills/, ~/.gemini/skills/). A declaration's configured scope is used unless overridden. Without an explicit or declared scope, an interactive install prompts for project or user scope; --yes, a non-TTY session, or CI skips the scope picker and defaults to project. Installation still requires confirmation: pass --yes in non-interactive runs. --force permits replacing modified owned files and does not skip confirmation.

An unowned destination or symbolic link causes reconciliation to fail without overwriting that destination. --force does not claim ownership or write through links.

Usage:

atmos ai skill install [source] [flags]

Flags:

--force

Replace modified owned copies. Does not overwrite unowned destinations or skip confirmation.

-y, --yes

Skip the confirmation prompt.

--path

Add a manual install directory while retaining the canonical Atmos copy. Relative paths resolve against the current working directory. With this flag, --scope, --global, --client, and --all-clients are ignored and are not saved for later updates. A new ad-hoc installation uses project scope; a declared source retains its configured scope.

-c, --client

AI client to distribute the skill to (repeatable): claude-code, vscode, gemini. Defaults to auto-detected clients.

--all-clients

Distribute the skill to every supported AI client.

--scope

Override the declaration's scope with project or user. Wins over --global. Without an explicit or declared scope, an interactive invocation prompts; otherwise the default is project. Also supported through ATMOS_AI_SKILL_SCOPE.

-g, --global

Alias for --scope user.

Install also accepts the source and reconciliation flags.

Examples:

# Install an official skill by name (offline)
atmos ai skill install atmos-terraform

# Install every bundled skill at once (offline)
atmos ai skill install

# Install a skill from GitHub
atmos ai skill install github.com/user/skill-name

# Install a specific version
atmos ai skill install github.com/user/skill-name@v1.2.3

# Force reinstall
atmos ai skill install github.com/user/skill-name --force

# Install without confirmation
atmos ai skill install github.com/user/skill-name --yes

# Install to a custom directory (skips auto-distribution)
atmos ai skill install atmos-terraform --path .github/skills

# Distribute to a specific AI client
atmos ai skill install atmos-terraform --client vscode

# Distribute to every supported AI client
atmos ai skill install atmos-terraform --all-clients

# Distribute into each client's personal, user-level directory
atmos ai skill install atmos-terraform --scope user

atmos ai skill list

List Atmos skills — both the official skills bundled with Atmos and any community skills installed on this system. A filled dot (●) marks an installed skill; a hollow dot (○) marks one that is available to install. The official catalog is embedded in the binary, so listing works offline.

Usage:

atmos ai skill list [flags]

Flags:

-d, --detailed

Show detailed information for each skill, including source, version, install date, and location.

--installed

Show only installed skills, hiding the rest of the available catalog.

-f, --format

Output format: table, json, yaml, csv, or tsv. Structured formats omit prose headers and ignore --detailed. Also supported through ATMOS_AI_SKILL_FORMAT.

Examples:

# List all skills (available and installed)
atmos ai skill list

# Show only installed skills
atmos ai skill list --installed

# Show detailed information
atmos ai skill list --detailed

atmos ai skill update

Refresh installed skills from their recorded sources. This updates bundled content to the version shipped in the running Atmos binary, refreshes local snapshots, and resolves moving Git refs. Revisions managed through !version continue to follow the selected version lock; update that lock before changing a managed revision.

Omit <name> to update installed sources in project scope; use --scope user for user installations. A named source or skill uses its declaration's scope unless overridden. Upgrading the Atmos binary alone does not refresh previously installed skill content.

Modified owned copies require --force; this is separate from --yes, which skips confirmation. A manual installation keeps its recorded manual destination on update. New client destinations require explicit client selection when updating a manual installation.

Usage:

atmos ai skill update [name] [flags]

Flags:

--force

Replace modified owned skill copies with source content. Does not skip confirmation or overwrite unowned destinations. Also supported through ATMOS_AI_SKILL_FORCE.

-y, --yes

Skip the confirmation prompt.

--path

Select a manual destination alongside the canonical Atmos copy. Relative paths resolve against the current working directory. Distribution flags are ignored, as for install.

-c, --client

AI client to distribute the updated skill to (repeatable): claude-code, vscode, gemini. Defaults to auto-detected clients.

--all-clients

Distribute the updated skill to every supported AI client.

--scope

Override the selected source's scope with project or user. No-argument update defaults to project scope. Wins over --global.

-g, --global

Alias for --scope user.

Update also accepts the source and reconciliation flags.

Examples:

# Update a single bundled skill if a newer version is available
atmos ai skill update atmos-terraform

# Update every installed bundled skill that has an update available
atmos ai skill update

# Skip the confirmation prompt
atmos ai skill update --yes

# Update and redistribute to a specific AI client
atmos ai skill update atmos-terraform --client vscode

# Replace locally modified owned copies and skip confirmation
atmos ai skill update --source Team --force --yes

atmos ai skill uninstall

Remove owned installed copies, including recorded client destinations in the selected scope. Omit <name> to uninstall recorded skills in that scope. Removal requires confirmation unless --force is supplied; --dry-run previews it without prompting. Source declarations remain in configuration.

Use --scope user (or --global) if the skill was installed with --scope user, so cleanup targets each client's personal, user-level skill directory instead of the project one. When neither --scope nor --global is given and the command is running in an interactive terminal, Atmos prompts you to choose project or user scope; --force, a non-TTY session, or CI skips the prompt and defaults to project.

User installations require an explicit user scope or an interactive user-scope selection. The non-interactive default never expands to both scopes. Symbolic links are rejected and left untouched. Client copies from legacy installations without ownership records are also retained.

Usage:

atmos ai skill uninstall [name] [flags]

Flags:

-f, --force

Skip confirmation and allow deleting modified owned copies. Does not delete unowned destinations or symbolic links.

-c, --client

Limit removal to recorded copies for these clients (repeatable): claude-code, vscode, gemini. Without a client filter, all owned copies in the selected scope are considered. The canonical copy is retained while other client copies remain.

--all-clients

Remove the skill from every supported AI client.

--scope

Distribution scope: project (default) or user. Use user to clean up a skill that was installed with --scope user. Wins over --global if both are set. When omitted (along with --global) in an interactive terminal, Atmos prompts you to choose; non-interactive runs (--force, no TTY, or CI) fall back to project.

-g, --global

Alias for --scope user.

Uninstall also accepts the source and reconciliation flags.

Examples:

# Uninstall a skill
atmos ai skill uninstall skill-name

# Uninstall every installed skill at once
atmos ai skill uninstall

# Uninstall without confirmation
atmos ai skill uninstall skill-name --force

# Remove the skill from a specific AI client only
atmos ai skill uninstall skill-name --client vscode

# Remove the skill from every supported AI client
atmos ai skill uninstall skill-name --all-clients

# Remove a skill that was installed with --scope user
atmos ai skill uninstall skill-name --scope user

Creating and Publishing Your Own Skill

Skills installed via atmos ai skill install <github-url> follow the same Agent Skills open standard format -- a single SKILL.md file with YAML frontmatter and a Markdown body containing the system prompt.

your-skill-repo/
├── SKILL.md             # Skill definition (required)
├── README.md            # Documentation (recommended)
├── examples/            # Usage examples (optional)
└── LICENSE              # License file (recommended)

The frontmatter declares metadata and tool access. The Markdown body is the AI system prompt.

SKILL.md (abbreviated)

---
name: terraform-expert
display_name: "Terraform Expert"
version: 1.0.0
author: Cloud Posse
description: >
  Specialized AI skill for Terraform component development,
  debugging, and best practices.
category: refactor

atmos:
  min_version: 1.50.0
  max_version: ""

tools:
  allowed:
    - atmos_describe_component
    - read_component_file
    - read_file
    - edit_file
    - execute_bash
  restricted:
    - edit_file
    - execute_bash

capabilities:
  - terraform-development
  - component-architecture

dependencies:
  - terraform

repository: https://github.com/yourorg/atmos-skill-terraform
---

# Skill: Terraform Expert

## Role

You are a specialized AI skill for Terraform component development...

## Instructions

[Detailed instructions for the AI skill go here]

## Restrictions

- Always confirm before executing destructive commands
- Never commit secrets or credentials to code

name

Unique skill identifier in kebab-case.

display_name

User-facing display name.

version

Semantic version (e.g., 1.2.3).

author

Author name or organization.

description

Brief description of skill purpose.

category

One of: general, analysis, refactor, security, validation, optimization.

atmos.min_version

Minimum compatible Atmos version.

tools.allowed

Tools the skill can use. Tools in restricted require user confirmation each time.

repository

GitHub repository URL.

Publishing Your Skill

Create a GitHub repository with a valid SKILL.md, tag a release, and share it:

terminal

mkdir atmos-skill-terraform && cd atmos-skill-terraform
git init

# Create SKILL.md with frontmatter and prompt (see format above)

git add . && git commit -m "Initial skill release"
git remote add origin git@github.com:yourorg/atmos-skill-terraform.git
git push -u origin main
git tag v1.0.0 && git push origin v1.0.0

Share your skill in Atmos Discussions and add the atmos-skill topic to your repository.

Naming Convention

• Repository: prefix with atmos-skill-, use kebab-case (e.g., atmos-skill-cost-optimizer)
• Skill name: no prefix, kebab-case (e.g., cost-optimizer)
• Display name: title case (e.g., "Cost Optimizer")

Tool Access and Security

Skills declare which tools they need. Review the tools.allowed section before installing any skill.

Review Before Installing

Always review skill source code on GitHub before installing skills that request:

• File write access (edit_file, write_stack_file, write_component_file)
• Command execution (execute_bash_command, execute_atmos_command)

Use the restricted field to require user confirmation for sensitive operations. A tool listed in both allowed and restricted means the skill can use it, but the user must approve each invocation.

Troubleshooting

Skill Not Found After Installation

Skill may be disabled or the registry is corrupted. Check with atmos ai skill list and inspect ~/.atmos/skills/registry.json.

Version Compatibility Error

Error: skill requires Atmos >= 1.50.0, but current version is 1.48.0

Upgrade Atmos (brew upgrade atmos) or install an older skill version (atmos ai skill install user/skill@v0.9.0).

Invalid Metadata Error

The skill's SKILL.md has malformed frontmatter. Report the issue to the skill author or try a different version tag.

Registry Corruption

terminal

# Backup and reset registry
cp ~/.atmos/skills/registry.json ~/.atmos/skills/registry.json.backup
rm ~/.atmos/skills/registry.json

# Reinstall skills
atmos ai skill install cloudposse/atmos

Declarative management

Use declarative sources to share skill selections and lock exact source revisions across a team.

Command	Effect
add <source> --name <label>	Create a configuration declaration
set <label> <field> <value>	Edit a declaration
remove <label>	Remove a declaration, retaining installations
sync [label]	Install or reconcile declared sources
sync --prune	Also remove obsolete owned copies
sync --check	Check installation state offline
sync --frozen	Install only from matching locks
sync --recover	Recover an interrupted transaction

Installation commands accept --source <label> to select a declaration explicitly and --track to select the version track. Configuration commands and reconciliation support --dry-run. The existing no-argument install continues to install all bundled skills.

Configuration command flags

atmos ai skill add ./team-skills --name Team
atmos ai skill set Team clients '[claude-code, gemini]'
atmos ai skill set Team ref '!version team-skills'
atmos ai skill remove Team --dry-run

set supports source, ref, kind, subpath, scope, plugins, include, exclude, and clients. List-valued fields take a YAML list. set and remove select the declaration using their positional label; they reject --name. Edits preserve comments and file permissions. For a declaration present in multiple configuration layers, removal requires one explicit --config file.

--name

Declaration label for add only. Required when adding a source.

--dry-run

Print the proposed configuration without writing it. Supported by add, set, and remove.

Source and reconciliation flags

These flags are registered on install, update, uninstall, and sync. Their applicability depends on the operation:

--source

Select a declared or recorded source explicitly. Use this when a source label conflicts with a bundled skill or local path.

--track

Select the version track for resolution. On uninstall, an explicit track restricts removal to installations recorded for that track; omitting it does not add a track filter.

--dry-run

Preview reconciliation without changing declarations, skill locks, or installed copies. May fetch sources to construct the preview. Cannot be combined with --check.

--frozen

Require matching resolution locks for install or sync. Can write installed copies and does not imply dry-run. Incompatible with update. Uninstall removes recorded copies without resolving a new source revision.

--check

Check installation state offline without writing skill state. Supported by install and sync; incompatible with update, uninstall, or --dry-run. Exits nonzero for missing, stale, modified, or obsolete copies.

--prune

Remove obsolete owned copies during reconciliation. Modified copies require force. Uninstall already removes selected owned copies, so prune adds no additional removal scope there.

Named legacy updates reject --dry-run, --check, and --frozen rather than sending these options to an updater that cannot enforce them. Reinstall the legacy skill to establish ownership before using source reconciliation.

Sync flags

sync [label] reconciles declarations without a confirmation prompt. It supports the shared flags above plus the following:

--scope

Override declaration scope with project or user. Also supported through ATMOS_AI_SKILL_SCOPE.

-c, --client

Limit target clients to claude-code, vscode, or gemini. Also supported through ATMOS_AI_SKILL_CLIENT.

--force

Replace modified owned copies or permit pruning them. Also supported through ATMOS_AI_SKILL_FORCE.

--recover

Recover an interrupted transaction for this project. Cannot be combined with --dry-run, --check, or --frozen.

Related Commands

atmos ai ask

Ask a one-time question

atmos ai chat

Start or resume an AI chat session

atmos ai exec

Run Atmos and shell commands via AI prompts

atmos ai sessions

Manage AI chat sessions