ammonhaggerty/a-primer-skills/primer-setup

Primer Setup

Overview

One-time guided setup for the AI Primer workflow. Designed for users who may have never opened a terminal. Progressive: present one step at a time, confirm before acting, verify after each change. Idempotent: detect what is already installed and skip completed steps. Safe to re-run at any point — nothing gets duplicated or overwritten.

This skill complements the AI Primer guidebook (Parts 2-3) and prepares the user's machine with every tool, connection, and configuration needed to build and ship full-stack products with Claude.

Design Principles

Five principles govern how this setup operates. Follow all of them throughout the process.

Never assume terminal familiarity

Explain every concept in plain English before executing any command. When a command runs, describe what it does and what the output means. Treat the terminal as a new environment the user is seeing for the first time. Avoid jargon; when technical terms are unavoidable, define them immediately.

One step at a time

Present a single action, explain it, ask permission, execute it, verify the result, then move on. Never batch multiple installs into one step. Never run ahead while the user is still absorbing the previous result. Patience is the default.

Idempotent

Detect what is already installed, configured, and working. Skip those steps entirely with a brief confirmation: "Git is already installed and configured — moving on." If something is installed but broken, fix it rather than re-installing. If something is partially configured, complete the configuration rather than starting over.

Honest

Clearly distinguish what Claude handles automatically from what requires the user to act. Account creation, OAuth flows, and browser-based sign-ins cannot be completed by Claude — say so plainly. Never pretend to do something that requires human interaction. State what will happen, what the user needs to do, and when to come back.

Platform-aware

Detect the operating system first and tailor every instruction accordingly. Mac-first instructions with Windows and Linux alternatives where relevant. Consult references/environment-checks.md for platform-specific detection commands and expected outputs.

Setup Flow

Work through these steps in order. Step 0 must pass before anything else — it catches system-level issues that cause cascading failures if not addressed upfront. Remaining steps include detection logic to skip work that is already done.

Step 0: System Health Check

Before installing anything, verify the system is ready. Run all checks from references/system-health-checks.md and present results as a clear pass/fail list. Example:

System health check:
 
  [pass] Admin access — your account can install software
  [pass] Temp directory — writable at /var/folders/k5/.../T/
  [pass] Home directory — writable
  [pass] Network — GitHub, npm, and Cloudflare are reachable
  [pass] Disk space — 45GB free
  [info] Shell — zsh (profile: ~/.zshrc)
  [info] macOS 15.3

If any blocker fails, stop here. Do not proceed to tool installation — it will fail. Explain the specific issue in plain English, provide the fix from the reference file, and ask the user to resolve it before continuing. The most common blocker is a fresh user account that needs a Mac restart.

If all blockers pass, move on. Warnings and informational items can be noted without stopping.

Step 1: Workspace Check

Detect the current working directory. Evaluate whether it is an appropriate workspace location.

If the user is in their home directory, Downloads, Desktop, or another unexpected location, explain the workspace convention: ~/Development is a single folder where all projects live. It is the place to always launch Claude from. Having one consistent workspace means Claude can see all projects and understand the full development environment. Every project created during the primer will live inside this folder.

If ~/Development does not exist, offer to create it. Explain what the mkdir command does before running it — it creates a new folder, nothing more. Guide the user to navigate into ~/Development before proceeding with the rest of setup.

If the user is already in ~/Development or a subdirectory of it, confirm the location and move on.

Step 2: Environment Detection

Run detection commands from references/environment-checks.md to survey the current state of the machine. Check all of the following:

• Operating system (macOS, Linux, or Windows)
• Node.js — installed and version is v18 or higher
• npm — installed (ships with Node.js)
• Git — installed and global user.name/user.email configured
• Homebrew — installed (macOS only)
• Wrangler — installed
• GitHub CLI (gh) — installed

Present findings in plain English. Use a clear list showing what is ready and what is missing or needs configuration. Example format:

Here is what I found on your system:
 
  [check] Node.js v22.4.1 — ready
  [check] npm 10.8.1 — ready
  [check] Git 2.43.0 — installed, but name and email not configured
  [x] Homebrew — not found
  [x] Wrangler — not found
  [x] GitHub CLI — not found

This step is diagnostic only. Make no changes yet. Let the user absorb the picture before proceeding.

Step 3: Account Verification

The guidebook directs users to create three accounts before running this skill: Claude, Cloudflare, and GitHub. Since the user is already running Claude Code, their Claude account is working. This step verifies the other two.

At this stage, wrangler and gh are likely not installed yet, so tool-based checks may not be available. Simply ask:

"The primer asks you to create Cloudflare and GitHub accounts before this step. Do you have both set up? And did you enable R2 Object Storage in your Cloudflare dashboard?"

If yes to all, confirm and move on. The accounts will be connected to the terminal in Step 5, after the necessary tools are installed.

If no, pause and walk them through creating the missing account(s):

• Cloudflare: "Open https://dash.cloudflare.com/sign-up — it's free and takes about two minutes. Let me know when you're done."
• R2 enablement: "In your Cloudflare dashboard, click R2 Object Storage in the left sidebar and follow the activation steps. This requires a credit card on file, but the free tier is generous — 10GB storage at no charge."
• GitHub: "Open https://github.com/signup — also free, also two minutes. Remember the email you use. Let me know when you're done."

Wait for confirmation before proceeding.

Step 4: Tool Installation

Work through missing tools one at a time. Skip anything already present and working. For each missing tool, follow this exact sequence:

1. Explain what it is and why it is needed, in one plain-English sentence
2. Show the command that will run and describe what it does
3. Ask permission before executing
4. Install using the platform-appropriate method from references/environment-checks.md
5. Verify installation succeeded by running the check command and confirming the output
6. Celebrate briefly — "Node.js is installed and ready" — before moving on

Installation order: Homebrew first (macOS, if missing), then Node.js, then Git, then GitHub CLI, then Wrangler. This order matters because later tools depend on earlier ones — Wrangler requires npm, which comes with Node.js, which on Mac is easiest to install through Homebrew.

Tool explanations to use:

• Homebrew — "A package manager for Mac. It installs developer tools with a single command instead of downloading installers from websites."
• Node.js — "The engine that runs JavaScript outside a browser. Nearly every web development tool depends on it."
• Git — "Version control. It tracks every change to your code so nothing is ever lost and you can always undo mistakes."
• GitHub CLI — "The command-line tool for GitHub. It lets Claude create repositories, push your code, and manage your projects."
• Mac: brew install gh
• Linux: Follow the instructions at https://github.com/cli/cli/blob/trunk/docs/install_linux.md
• Windows: winget install --id GitHub.cli
• Wrangler — "The Cloudflare command-line tool. It deploys your projects to the internet."

Git configuration: After confirming Git is installed, check whether user.name and user.email are configured globally. If either is missing, ask the user for their name and email address. Remind them: "Use the same email you used for GitHub — this links your code changes to your GitHub profile." Configure with git config --global. Explain: "Git labels every change with your name and email — think of it as signing your work."

Git default branch: Set the default branch name to main (the modern standard). Without this, Git defaults to master on fresh installs:

git config --global init.defaultBranch main

Git HTTPS preference: Also configure Git to use HTTPS instead of SSH for GitHub. This prevents authentication errors when installing plugins and cloning repositories, since most beginners do not have SSH keys set up:

git config --global url."https://github.com/".insteadOf "git@github.com:"

Both of these are silent, one-time configurations. No explanation is needed unless the user asks — just run them as part of Git setup.

If any installation fails, consult references/troubleshooting.md for the specific error symptom before attempting alternative approaches.

Step 5: Account Connections

Connect the user's Cloudflare and GitHub accounts to the terminal tools installed in Step 4. Both connections are required.

GitHub authentication:

Check with gh auth status. If not authenticated:

"Now let's connect GitHub to your terminal. I'll start the login process — a browser window will open where you'll sign in to GitHub and authorize the connection."

Run gh auth login. Walk the user through the interactive prompts:

• Select GitHub.com
• Select HTTPS as the preferred protocol
• When asked to authenticate, choose Login with a web browser
• Follow the browser prompts to authorize

Verify with gh auth status. If it shows the user's GitHub username, confirm: "GitHub is connected as [username]."

Cloudflare authentication:

Check with wrangler whoami. If not authenticated:

"Now let's connect Cloudflare. A browser window will open — sign in with your Cloudflare account and click 'Allow'."

Important: The wrangler login command has a built-in timeout. Since the user already has an account, this should be quick. If the user hasn't created an account yet, direct them to dash.cloudflare.com/sign-up first.

Run wrangler login with a 3-minute timeout. After the user confirms the OAuth flow is complete, verify with wrangler whoami.

If the login timed out, offer to try again. If verification fails, consult references/troubleshooting.md for authentication issues.

Step 6: MCP Server Configuration

Install MCP servers using claude mcp add CLI commands. These write to ~/.claude.json and persist across all sessions automatically. Consult references/mcp-server-configs.md for exact commands.

Required — install both:

• context7 — "This lets me pull the latest documentation for any library instead of relying on potentially outdated training data." Run: claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest