setup-agent-workstation

name	setup-agent-workstation
description	Configure, audit, migrate, or reproduce a macOS or Windows development workstation for AI and agent engineering. Use when Codex needs to plan or execute new-computer setup, install developer tools, package managers, runtimes, CLIs, editors, Docker/WSL/GPU support, SSH/Git credentials, or project dependency bootstrapping across machines.

Setup Agent Workstation

Overview

Use this skill to turn a fresh macOS or Windows computer into a reliable AI/agent engineering workstation. Prefer an audited, staged setup over a one-shot install script.

Operating Rules

• Start with inventory. Identify OS, architecture, admin rights, package managers, shell, GPU/WSL status, and existing developer tools before proposing installs.
• Separate required, recommended, and optional tools. Do not install AI CLIs, GPU stacks, databases, or paid/proprietary software unless the user wants them.
• Prefer package managers and idempotent commands. Verify fast-moving package IDs with brew info, brew search, winget search, or official docs before running installs.
• Treat secrets carefully. Never ask the user to paste API keys into chat; guide them to local environment files, OS credential stores, password managers, or project secret managers.
• Avoid destructive setup. Do not overwrite dotfiles, shell profiles, SSH config, package manager config, or existing Python/Node installs without backing up or showing a diff.
• Prefer per-project dependency files over global packages. Use global tools mainly for package managers, shells, editors, Docker, Git, and small CLIs.
• Present commands in phases with verification after each phase. If executing locally, stop and report exact failures before trying a different package manager.

Workflow

1. Build or infer the workstation profile.

   • Use references/profile-template.md when the request is broad, ambiguous, or migration-focused.
   • Ask only for high-impact missing choices: target OS, package manager preference, editor, local GPU needs, Docker/WSL needs, and AI provider/tooling preferences.

2. Run a read-only inventory.

   • On Windows, inspect PowerShell, winget, Git, WSL, Docker, GPU drivers, Node, Python, and uv.
   • On macOS, inspect sw_vers, architecture, Xcode Command Line Tools, Homebrew, Git, Docker, Node, Python, and uv.
   • Capture version output and missing tools. Do not install during this phase.
   • Prefer bundled inventory scripts when available:

bash scripts/inventory_macos.sh --format json

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/inventory_windows.ps1 -Format json

3. Generate a staged setup plan.
   • Use scripts/generate_setup_plan.py for a first-pass plan:

python scripts/generate_setup_plan.py --os auto --profile agent

• Use --os windows or --os macos when planning for another machine.
• Use --profile minimal, agent, gpu, or full depending on scope.
• Use --format json when another tool or agent should consume the plan.
• Use --list-categories to inspect supported opt-in categories.
• Edit the output for the user's actual preferences before execution.

4. Execute in phases.

   • Phase 0: OS updates, admin rights, package manager, shell baseline.
   • Phase 1: Git, SSH, terminal, editor, core CLI tools.
   • Phase 2: Python/Node runtimes and package managers.
   • Phase 3: Docker, WSL, databases, browsers, Playwright, and local services.
   • Phase 4: AI/agent tooling, provider CLIs, local model tools, GPU stack.
   • Phase 5: dotfiles, project bootstrapping, verification, and handoff notes.

5. Verify and document.

   • Run version checks for installed tools.
   • Create a short "what changed" summary with commands run, skipped items, remaining manual steps, and any restart/sign-in requirements.
   • For migrations, save the final package list and config notes so the setup can be reproduced later.

Inventory Commands

Use these as starting points, then adapt to the user's shell.

Windows PowerShell:

$PSVersionTable
Get-ComputerInfo | Select-Object OsName, OsVersion, CsSystemType, CsManufacturer, CsModel
winget --version
git --version
gh --version
wsl --status
docker --version
node --version
python --version
uv --version
nvidia-smi

macOS shell:

sw_vers
uname -m
xcode-select -p
brew --version
git --version
gh --version
docker --version
node --version
python3 --version
uv --version
system_profiler SPDisplaysDataType

Missing commands are expected on fresh machines; record them rather than treating them as errors.

Profiles

• minimal: Git, shell, editor, package manager, Python/Node basics, and a small set of diagnostic CLI tools.
• agent: The default for AI agent engineering. Adds Docker, Playwright/browser automation readiness, uv, Node package managers, GitHub CLI, quality tools, and optional AI provider tooling.
• gpu: Use when local model inference/training, CUDA, Apple Silicon acceleration, or WSL GPU support matters.
• full: Broad personal workstation setup with optional databases, local model tools, cloud CLIs, and extra productivity apps.

Data Maintenance

• Read data/profiles.json, data/macos.json, and data/windows.json before changing default tools or categories.
• Keep default profiles conservative. Heavy local model tools, GPU stacks, databases, and cloud CLIs should remain opt-in.
• Add verification commands for every package-manager-installed tool.
• Mark machine-specific, driver, CUDA, credential, and account setup as manual.

References

• Read references/macos.md before planning or executing macOS setup.
• Read references/windows.md before planning or executing Windows setup.
• Read references/ai-agent-stack.md when selecting AI/agent engineering tools, runtimes, CLIs, browsers, databases, and local model options.
• Read references/profile-template.md when creating a reusable machine profile, migration checklist, or user questionnaire.

Execution Guidance

When the user asks to set up the current machine, show the staged plan before installing anything substantial. For small missing tools, it is fine to install after naming the package manager and verification command. For a new remote or future machine, produce a script or checklist and clearly mark commands that need manual review.