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

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 bundled skills to the latest version shipped with your atmos binary
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 52 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:

Router (AGENTS.md) -- A lightweight index that maps user tasks to the right skill
Skill (SKILL.md) -- Domain-specific instructions, patterns, and examples
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:

Follow the existing folder structure: agent-skills/skills/<skill-name>/SKILL.md
Keep the primary SKILL.md under 500 lines for optimal context usage
Place detailed reference material in references/ subdirectories
Update AGENTS.md to include your skill in the routing table
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) or from a GitHub repository.

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.

By default, the skill is also auto-distributed into any detected AI client's project-local skill directory (.github/skills/ for VS Code/Copilot, .claude/skills/ for Claude Code, .gemini/skills/ for Gemini), so it works with zero extra flags. Use --client/--all-clients to control which clients receive a copy, or --path to take full manual control of the install location (this skips auto-distribution).

Use --scope user (or --global) to distribute into each client's personal, user-level skill directory instead (~/.claude/skills/, ~/.copilot/skills/ for VS Code/Copilot, ~/.gemini/skills/), so the skill is available across every project rather than just this 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; --yes, a non-TTY session, or CI skips the prompt and defaults to project.

If a client's target directory already exists as a symbolic link (for example this repo's own .claude/skills/<name> entries, which intentionally point into agent-skills/skills/<name> for contributor auto-discovery), that client is skipped with a warning instead of writing through the symlink.

Usage:

atmos ai skill install [source] [flags]

Flags:

--force: Reinstall if the skill is already installed.
-y, --yes: Skip the confirmation prompt.
--path: Override the skill install directory (default: ~/.atmos/skills). Relative paths resolve against the current working directory, e.g. --path .github/skills for VS Code/Copilot auto-discovery. Setting --path skips auto-distribution to AI clients.
-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: Distribution scope: project (writes into this repo's client directories, default) or user (writes into each client's personal, user-level directory instead). Wins over --global if both are set. When omitted (along with --global) in an interactive terminal, Atmos prompts you to choose; non-interactive runs (--yes, no TTY, or CI) fall back to project.
-g, --global: Alias for --scope user.

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.

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`

Update installed bundled skills to their latest catalog version. Bundled skills are static copies made at install time — upgrading the atmos binary alone does not refresh a skill you already installed, even if that release bundles newer skill content. update compares each installed bundled skill's recorded version against the catalog embedded in the running binary and reinstalls only the ones that are actually outdated; skills already at the current version are left untouched.

Omit <name> entirely to update every installed bundled skill that has a newer version available (a single confirmation, not one per skill). Skills installed from a GitHub repository are not supported yet — there's no cheap way to check whether a git-sourced skill's upstream has moved without re-fetching it; run atmos ai skill install <source> --force to refresh one of those manually.

An outdated skill is reinstalled the same way atmos ai skill install <name> --force would install it, so the same client-distribution and scope flags apply.

Usage:

atmos ai skill update [name] [flags]

Flags:

-y, --yes: Skip the confirmation prompt.
--path: Override the skill install directory (default: ~/.atmos/skills). Relative paths resolve against the current working directory.
-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: Distribution scope: project (default) or user. Wins over --global if both are set.
-g, --global: Alias for --scope user.

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

`atmos ai skill uninstall`

Remove an installed skill. Any copies auto-distributed to AI clients during install are removed as well. Omit <name> entirely to uninstall every installed skill at once.

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.

If a client's copy is actually a symbolic link (for example this repo's own .claude/skills/<name> entries), it is left in place with a warning rather than being deleted.

Usage:

atmos ai skill uninstall [name] [flags]

Flags:

-f, --force: Skip the confirmation prompt.
-c, --client: AI client to remove the skill from (repeatable): claude-code, vscode, gemini. Defaults to auto-detected clients.
--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.

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

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

Description​

What Are Agent Skills?​

Official SKILL.md Format​

Contributing an Official Skill​

Usage​

Subcommands​

atmos ai skill install​

atmos ai skill list​

atmos ai skill update​

atmos ai skill uninstall​

Creating and Publishing Your Own Skill​

Publishing Your Skill​

Tool Access and Security​

Troubleshooting​

Skill Not Found After Installation​

Version Compatibility Error​

Invalid Metadata Error​

Registry Corruption​

Related Commands​

Description

What Are Agent Skills?

Official SKILL.md Format

Contributing an Official Skill

Usage

Subcommands

`atmos ai skill install`

`atmos ai skill list`

`atmos ai skill update`

`atmos ai skill uninstall`

Creating and Publishing Your Own Skill

Publishing Your Skill

Tool Access and Security

Troubleshooting

Skill Not Found After Installation

Version Compatibility Error

Invalid Metadata Error

Registry Corruption

Related Commands