# 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:** [AI Skills Configuration](/cli/configuration/ai/skills) for configuring skills in `atmos.yaml` |
[Skill Marketplace](/ai/skill-marketplace) for browsing available skills

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

## 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). 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 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`
  . 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
```

## Related Commands