EAI-1703: Atlas CLI skill

[mongodben]

MongoDB Agent Skill Submission

Skill Information

Skill Name: MongoDB Atlas CLI
Skill Directory: skills/mongodb-atlas-cli

Use Case

Drive MongoDB Atlas from the terminal via the atlas CLI — install and authenticate the CLI, then run commands against Atlas resources (clusters, projects, users, network access, migrations, etc.). Detailed playbooks for cluster management; high-level map for everything else.

Value Proposition

The Atlas CLI has a large surface area with sharp edges: interactive auth that hangs non-interactive shells, long-running --watch commands that block agent turns for 7-10 min, tier-specific restrictions (FLEX can't pause, M0 → M10+ uses a different subcommand than M10+ → M30), silent Atlas policies (30-day auto-resume), and config-file-only changes (region/provider moves have no flag). Unskilled agents improvise — sometimes confidently wrong. This skill encodes the corrections.

Special Considerations

Requires the atlas CLI on PATH. Cloud operations require Atlas auth (interactive login or Service Account env vars); local deployments require Docker.

Validation Prompts

Five eval cases in testing/mongodb-atlas-cli/evals/evals.json, each exercising a distinct skill section.

1. Auth hand-off

• Case: "I just installed the Atlas CLI. Can you log me in?"
• Expected behavior: Does NOT run atlas auth login itself (interactive, hangs a non-interactive shell). Hands off to the user with two options: interactive login they run themselves, or Service Account env vars (MONGODB_ATLAS_CLIENT_ID / CLIENT_SECRET) they add to their own shell profile.
• No-skill outcome: Proposes atlas auth login and offers to run it for the user. Would hang the agent session.
• With-skill outcome: Refuses to run interactive login, presents both hand-off paths with concrete commands, warns against pasting credentials into chat.

2. M0 upgrade to M10 (correct subcommand + warnings)

• Case: "I have a free-tier cluster called demo and I want to move it to M10 on AWS with 10GB disk."
• Expected behavior: Uses atlas clusters upgrade (NOT atlas clusters update — that command only works on M10+ and fails on M0/FLEX). Surfaces three warnings: downtime during tier change, billing starts on the paid tier, one-way (can't scale back to M0/FLEX).
• No-skill outcome: Gets the command right (upgrade) but only surfaces 1 of 3 warnings (billing). Misses downtime entirely; one-way framing is weak.
• With-skill outcome: Correct command, all three warnings explicit.

3. Migrate scope

• Case: "I want to migrate my self-hosted MongoDB 7.0 replica set into Atlas. Can you set up the live migration?"
• Expected behavior: Does NOT try to drive the migration with atlas liveMigrations — that CLI surface only handles push migrations from Cloud-Manager-monitored sources, not arbitrary self-managed deployments. Asks whether the source is in Cloud Manager; if not, hands off to Pull Live Migration (Atlas UI), mongosync, or mongomirror. Flags M10+ destination requirement.
• No-skill outcome: Vague about CLI vs UI, doesn't know atlas liveMigrations exists, no mention of mongosync/mongomirror, misses M10+ destination constraint.
• With-skill outcome: Cleanly distinguishes Push (Cloud-Manager-required, CLI-driven) from Pull (UI-driven), provides both doc links, flags M10+ destination, asks the right clarifying questions.

4. Region change requires --file

• Case: "We need to move our prod-cluster from AWS us-east-1 to us-west-2 for latency reasons."
• Expected behavior: Recognizes atlas clusters update has no --region flag; region/provider changes require --file cluster-config.json. Workflow: dump current spec with describe --output json, edit, apply via update --file. Cross-region moves trigger an initial sync (not rolling) — elevated impact during cutover.
• No-skill outcome: Gets the --file workflow right, but gives wrong downtime advice — claims the migration is "rolling node-by-node" with "no downtime." Actual behavior per Atlas docs: initial sync, elevated latency and oplog pressure. A user planning no maintenance window based on this answer would be surprised.
• With-skill outcome: "Triggers an initial sync rather than a rolling update," recommends a maintenance window, flags VPC peering and region-bound backup snapshots.

5. Pause 30-day cap

• Case: "Pause my Cluster0 cluster. I'll be back in about a month after we finish the Q4 launch."
• Expected behavior: Runs atlas clusters pause Cluster0. Surfaces the 30-day auto-resume cap — user said "about a month," so Atlas will likely auto-resume and billing will restart before they return. Mentions 60-min minimum uptime before re-pausing, and that storage is still billed while paused.
• No-skill outcome: Confidently states the pause limit is 7 days (wrong — it's 30). Builds an elaborate workaround plan (weekly re-pausing, terminate + restore) on top of the incorrect number.
• With-skill outcome: Correct 30-day cap, auto-resume + billing-restart warning, M0/FLEX tier exceptions, NVMe + disk >95% constraints, 60-min minimum uptime.

Author Self-Validation

• Ran skill-validator (passed, medium contamination score is false positive — multi-cloud tool references).
• Ran manual paired subagent evals (with-skill vs baseline) on all 5 cases. Baseline failed 2/5 outright (including two confident factual errors — wrong pause duration, wrong cross-region downtime claim) and partial-passed 3/5. With-skill passed 5/5.
• Tested skill with LLMs using the five prompts above

SME Review

SME: @

Additional Context

• Skill is scoped to detailed cluster-management playbooks + a high-level command map for the rest of the CLI surface. Non-cluster surfaces link out to atlas <command> --help and the relevant docs rather than being inlined.
• Every command and flag in the skill was validated against live atlas <cmd> --help output at authoring time.
• Known gap: no dedicated sections for db users, access lists, backups, or Atlas Search — these are covered in the high-level map and left to --help / docs.

[Copilot]

Pull request overview

Adds a new MongoDB Atlas CLI skill to guide agents in safely installing/authenticating the atlas CLI and performing common Atlas operations (with emphasis on cluster management and avoiding interactive/long-running commands that break agent shells).

Changes:

• Introduces skills/mongodb-atlas-cli/SKILL.md with end-to-end CLI setup + cluster-management playbooks and safety guardrails.
• Adds testing/mongodb-atlas-cli/evals/evals.json with 5 eval prompts covering auth hand-off, M0→M10 upgrade semantics, migration scope, region change via --file, and pause auto-resume constraints.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
skills/mongodb-atlas-cli/SKILL.md	New skill documentation/playbooks for Atlas CLI usage, including non-interactive-safe patterns and cluster lifecycle guidance.
testing/mongodb-atlas-cli/evals/evals.json	Adds evaluation cases to validate the skill’s intended behaviors and guardrails.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This section uses atlas orgs list, but earlier the skill enumerates the top-level command as organizations. To avoid confusion for users copying commands, either use the canonical atlas organizations list form here or explicitly note that orgs is an alias.

Suggested change

	atlas orgs list
	atlas organizations list