# Configure AI Assistants

Configure your AI coding assistant to use Atmos agent skills. Skills give the AI deep knowledge of Atmos conventions,
stack configuration, Terraform orchestration, and more. Each tool has its own installation method.

> **Key points**
>
> - Claude Code: install via the Cloud Posse plugin marketplace
> - Cursor, Windsurf, GitHub Copilot: reference `AGENTS.md` from the Atmos repo
> - Gemini CLI, OpenAI Codex: symlink or copy the `agent-skills/` directory
> - Skills activate automatically -- no special syntax needed

## Install Atmos Skills

Atmos users install the `atmos` binary -- you do **not** need to clone the Atmos repository. Skills are installed
separately through your AI tool's own mechanism.

### Claude Code Plugin (Recommended)

The fastest way to add Atmos skills is via the Cloud Posse plugin marketplace. No files to copy -- skills
are installed with two commands and persist across sessions:

```bash
# One-time marketplace setup
/plugin marketplace add cloudposse/atmos

# Install the Atmos skills plugin
/plugin install atmos@cloudposse
```

To auto-configure skills for your entire team, add marketplace and plugin settings to your
project's `.claude/settings.json` (see [Team Auto-Discovery](#team-auto-discovery) below).

### Other AI Tools

Gemini CLI, OpenAI Codex, Cursor, Windsurf, and GitHub Copilot do not have third-party marketplace support
for Atmos skills. For these tools, use Atmos vendoring to pull the skills into your project.

Add the following source to your `vendor.yaml`:

```yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
metadata:
  name: atmos-agent-skills
  description: Vendor Atmos AI agent skills
spec:
  sources:
    - component: "agent-skills"
      source: "github.com/cloudposse/atmos.git//agent-skills?ref={{.Version}}"
      version: "main"
      targets:
        - "agent-skills"
```

Then pull the skills:

```bash
atmos vendor pull --component agent-skills
```

This downloads the `agent-skills/` directory into your project with the correct structure intact.
To update skills later, run the same command again.

Then configure your AI tool using the instructions below.

## Tool-Specific Configuration

### Claude Code

**Config directory:** `.claude/` | **Instruction file:** `CLAUDE.md` | **Skills:** `.claude/skills/` or via plugins

The recommended way to install Atmos skills in Claude Code is via the Cloud Posse plugin marketplace.

#### Plugin Installation (Recommended)

```bash
# Step 1: Add the Cloud Posse marketplace (one-time setup)
/plugin marketplace add cloudposse/atmos

# Step 2: Install the Atmos skills plugin (all 21 skills)
/plugin install atmos@cloudposse
```

Skills are available immediately after installation and persist across sessions. One plugin installs all 21 skills -- the AI loads only the relevant skill on demand, so there is no performance overhead.

**How it works**: The `cloudposse/atmos` GitHub repository serves as the marketplace. When you add it,
Claude Code fetches `.claude-plugin/marketplace.json` directly from the repo via the GitHub API. When you
install the plugin, Claude Code downloads the skills directory and caches it locally. No central registry or
approval process is involved -- the GitHub repo IS the marketplace.

#### Uninstalling

```bash
# Remove the plugin
/plugin uninstall atmos@cloudposse

# Remove the marketplace (optional)
/plugin marketplace remove cloudposse
```

#### Team Auto-Discovery

Teams can auto-configure the marketplace for all team members by adding to the project's `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "cloudposse": {
      "source": {
        "source": "github",
        "repo": "cloudposse/atmos"
      }
    }
  },
  "enabledPlugins": {
    "atmos@cloudposse": true
  }
}
```

When team members trust the repository folder, Claude Code prompts them to install these plugins automatically.

#### Official Anthropic Marketplace (Alternative)

Atmos plugins may also be available in the
[official Anthropic marketplace](https://github.com/anthropics/claude-plugins-official). If listed there,
you can install without adding a marketplace first:

```bash
/plugin install atmos@claude-plugin-directory
```

Check the "Discover" tab in `/plugin` to see if Atmos plugins are available in the official directory.

#### Auto-Discovery (Atmos Contributors)

When working directly in the Atmos repo, Claude Code automatically discovers skills via the
`.claude/skills` symlinks -- no plugin installation needed.

```bash
# Skills are auto-discovered in the Atmos repo
claude

# Or add the skills directory from another location
claude --add-dir /path/to/atmos/agent-skills
```

Claude Code loads `AGENTS.md` as the router, then activates the relevant `SKILL.md` based on your question.

### OpenAI Codex

**Config directory:** `~/.codex/` | **Instruction file:** `AGENTS.md` (native) | **Skills:** via Agent Skills format

OpenAI Codex CLI natively reads `AGENTS.md` from the repository root -- it co-created this standard.
Codex does not have a `--add-dir` flag or a dedicated skill installation command.

```bash
# Codex reads AGENTS.md natively from the repo root
# The agent-skills/AGENTS.md router is already in the repository

# To point Codex at the skills, copy AGENTS.md to the repo root
cp agent-skills/AGENTS.md AGENTS.md
```

The lookup order is: `AGENTS.override.md` > `AGENTS.md` > fallback files configured in `~/.codex/config.toml`.

Alternatively, add a `CODEX.md` file at the repository root that references the skills:

```markdown
<!-- CODEX.md -->
# Atmos Project Instructions

This project uses Atmos for infrastructure orchestration.
See agent-skills/AGENTS.md for the full skill index.

When working with Atmos stacks, components, or CLI commands,
load the relevant skill using the paths in the AGENTS.md skill index.
```

### Gemini CLI

**Config directory:** `.gemini/` | **Instruction file:** `GEMINI.md` | **Subagents:** `.gemini/agents/*.md`

Gemini CLI reads `GEMINI.md` from the project root (configurable via `context.fileName` in `settings.json`).
It supports the Agent Skills specification and subagents with YAML frontmatter.

```bash
# Symlink skills to the Gemini-recognized path
ln -s agent-skills .gemini/skills
```

You can also reference the skills in your `GEMINI.md` file:

```markdown
<!-- GEMINI.md -->
For Atmos-specific guidance, see agent-skills/AGENTS.md.
Load the relevant skill using the paths in the AGENTS.md skill index.
```

### Cursor

**Config directory:** `.cursor/` | **Rules:** `.cursor/rules/*.mdc` | **Agents:** `.cursor/agents/*.md`

Cursor co-created the `AGENTS.md` standard and reads it natively. It also supports subagents in
`.cursor/agents/*.md` with YAML frontmatter (since Cursor 2.4).

The **primary integration path** is adding an `.mdc` rule file that references the skills router.
Cursor `.mdc` files require YAML frontmatter with `description`, `globs`, and `alwaysApply` fields --
without frontmatter, the rule is treated as "Manual" and will not auto-load:

```text
# .cursor/rules/atmos.mdc
---
description: Atmos infrastructure orchestration guidance
globs: "*.yaml, *.tf"
alwaysApply: false
---
@agent-skills/AGENTS.md
```

With this configuration, Cursor auto-attaches the Atmos skill router when editing YAML or Terraform
files, and the agent can also discover it based on the description for any Atmos-related question.

### Windsurf

**Config directory:** `.windsurf/` | **Rules:** `.windsurf/rules/` or `.windsurfrules` | **AGENTS.md:** auto-discovered

Windsurf automatically discovers `AGENTS.md` files in the workspace and subdirectories, applying them
as scoped instructions to Cascade. For guaranteed context loading, also add a pointer in your
`.windsurfrules` file:

```text
# .windsurfrules
Always refer to agent-skills/AGENTS.md for Atmos commands and configuration patterns.
Load the relevant skill using the paths in the AGENTS.md skill index.
```

This ensures Windsurf applies Atmos context during all Cascade sessions, even if auto-discovery
does not trigger for nested files.

### GitHub Copilot

**Config directory:** `.github/` | **Instructions:** `.github/copilot-instructions.md` | **Agents:** `.github/agents/*.md`

GitHub Copilot supports custom instructions, domain-specific instruction files in `.github/instructions/*.md`,
and custom agents in `.github/agents/*.md`. It reads `AGENTS.md` natively.

```markdown
<!-- .github/copilot-instructions.md -->
See agent-skills/AGENTS.md for Atmos-specific guidance.
When working with Atmos, load the relevant skill using the paths in the AGENTS.md skill index.
```

### Other Tools

For any AI tool that supports project-level context files:

1. **Symlink** `agent-skills/` into the tool's configuration directory
2. **Reference** `AGENTS.md` as the entry point in the tool's instruction file
3. **Point** the tool at individual `SKILL.md` files for focused context

The skills use standard Markdown with YAML frontmatter, which is universally supported by all AI tools.

**Tool-specific paths:**

| Tool | Config Directory | Instruction File |
|------|-----------------|-----------------|
| Antigravity | `.agent/` | Inherits `~/.gemini/GEMINI.md` |
| Amazon Q Developer | `.amazonq/` | JSON agent configs in `.amazonq/cli-agents/` |
| JetBrains Junie | `.junie/` | `.junie/guidelines.md` (also reads `AGENTS.md`) |

```bash
# Antigravity (uses Agent Skills format natively)
ln -s agent-skills .agent/skills

# JetBrains Junie (reads AGENTS.md as fallback)
cp agent-skills/AGENTS.md AGENTS.md
```

## How Skills Are Activated

You do **not** invoke skills manually. Your AI tool activates the right skill automatically based on your question:

1. **At session start**, the AI loads lightweight metadata (name and description) from each installed skill
2. **When you ask a question** about Atmos, the AI matches your question to the most relevant skill's description
3. **The full skill content** loads on demand, giving the AI accurate, up-to-date guidance
4. **Reference files** load only when the AI needs deeper detail (e.g., full command reference, schema examples)

For example, if you ask _"How do I configure stack imports?"_, the AI automatically activates the `atmos-stacks`
skill and uses its content to answer correctly -- no special syntax or commands needed.

:::tip
For Claude Code plugin installations, activation uses the `description` field in each SKILL.md's frontmatter.
For file-based installations (Codex, Gemini, Windsurf, Copilot), the `AGENTS.md` router maps your task to
the right skill via its skill index table. Both mechanisms are automatic.
:::

## Related

- [AI Agent Skills](/ai/agent-skills) -- Full list of available skills, folder structure, and SKILL.md format
- [Setup Editor (IDE)](/projects/setup-editor) -- Configure VS Code and DevContainers for Atmos