Skip to main content

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.

You will learn

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

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

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:

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​

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)​

# 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​

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

{
  "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. If listed there, you can install without adding a marketplace first:

/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.

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

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​