# 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](/ai/skills) to browse every skill |
[AI Skills Configuration](/cli/configuration/ai/skills) for configuring skills in `atmos.yaml`

## Description

Skills are specialized AI assistants that provide expert knowledge for specific domains. They follow the
[Agent Skills](https://agentskills.io) 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

:::tip 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.

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

See [Global Flags](/cli/global-flags) for details.
:::

## What Are Agent Skills?

Atmos ships  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](/ai/skills). 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](/projects/setup-editor/ai-assistants).

### Official SKILL.md Format

**File:** `SKILL.md`

```markdown
---
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](/ai/skills)
   (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](https://agents.md/) for project-level AI instructions, and
[Agent Skills](https://agentskills.io/specification) (`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](/ai/skills) -- no separate doc update needed. See the
[Atmos Contributing Guide](/community) for general contribution guidelines.

## Usage

```shell
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:**

```shell
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:**

```shell
# 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:**

```shell
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:**

```shell
# 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:**

```shell
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:**

```shell
# 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:**

```shell
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:**

```shell
# 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](https://agentskills.io) 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.

**File:** `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:

```shell
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](https://github.com/cloudposse/atmos/discussions) and add the `atmos-skill` topic to your repository.

:::tip 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.

:::danger 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

```shell
# 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
```

## Related Commands