julianrubisch Rails Bootstrap (One-time Mac Setup)
Take a Mac user from a near-blank dev environment to a Rails app running in their browser. Conversational interview, automated execution, pedagogical voice. Delegates Rails app generation to jr-rails-new; this skill handles the prerequisites and the wiring.
Read @references/guide.md and follow it. Do not proceed without it.
When to use
- Brand-new Mac with no dev tools installed.
- First Rails app on this machine.
- User is non-technical and wants a guided path.
Not for: generating additional Rails apps after the machine is set up (use jr-rails-new directly), per-project work (use jr-rails-classic / jr-rails-phlex), deployment (out of scope), or SSH key setup (out of scope - HTTPS only).
Hard preconditions (assumed, not verified)
- Mac on macOS 14+
- Claude Code already installed, authenticated, running (this skill is invoked from Claude Code; it cannot install its host)
- Claude Pro or Max subscription (no API-key spend assumed)
If any of these is missing the user cannot reach this skill at all - so no defensive check.
Phase summary
| Phase | What | Output |
|---|---|---|
| A | Sanity (macOS version, subscription) + fresh-or-existing branch | BRANCH, optional PROJECT_PATH |
| B | Prereqs: Xcode CLT, Homebrew, mise, Ruby 4.0, Node 22 | tool chain ready |
| C | Git hosting CLI(s): gh, glab. Auth happens in a separate Terminal window | gh/glab authenticated on host shell |
| D | Skills pack via npx skills add julianrubisch/skills -g -y |
jr-rails-* available |
| E | App: jr-rails-new (fresh branch) or smoke-check (existing branch) |
working Rails project |
| F | Git remote: create new or attach existing | origin set, first push (fresh) |
| G | Run the app: read project's CLAUDE.md, fall back to bin/dev, open browser |
"It works" |
Full per-step detail (commands, prompts, error messages, pedagogical "why this matters" lines) lives in references/guide.md. Load it at the start of a session and step through it.
Hard rules
Idempotent everywhere. Every prereq check is "✓ already installed (version X)" if present. Every auth check is "✓ already authenticated as Y". Re-running on a configured Mac must complete without side effects beyond producing a fresh SETUP_SUMMARY.md.
Never run interactive auth flows inside the Claude Code session. gh auth login and glab auth login write credentials to the host shell's keychain/config. If you run them inside the Claude Code Bash tool, the credentials may land in the wrong context or get truncated by tool output buffering. Instruct the user to open a fresh Terminal window and run the auth command there. Wait for explicit confirmation before proceeding. See references/auth-handoff.md for the exact script.
Existing-app branch is read-only on user files. Never overwrite their project, never rails new over it, never git init, never run a destructive migration. The only write into an existing project's tree is git remote add origin (Phase F), and only if no remote is currently set.
Visible checklist. Print a running progress line at every step: Step 6 of 20: installing mise.... The user must be able to see where in the process they are.
Pause between phases. Confirm with the user before crossing a phase boundary. Skip the pause only if the user opts into non-interactive ("run all") mode at the start.
Plain-language errors. Never paste a raw stack trace at the user. Translate: "Homebrew install failed because /usr/local is owned by another user. Fix: run sudo chown -R $(whoami) /usr/local in Terminal." Show the underlying error after the explanation if needed, not before.
Final artifact. Always write <project>/SETUP_SUMMARY.md at the end (template in references/setup-summary-template.md). This is the audit trail; future invocations can read it instead of re-detecting.
Voice. The user is non-technical. One short "why this matters" sentence before each install step. Reassurance during slow steps (e.g. compiling Ruby). No jargon without a one-line definition. Use hyphens, not em-dashes in any prose written for the user.
File layout
jr-rails-bootstrap/
├── SKILL.md # This file (entry point)
└── references/
├── guide.md # Full phase-by-phase walkthrough (load first)
├── auth-handoff.md # Phase C step 10 script for separate-shell auth
└── setup-summary-template.md # Final artifact template
Progressive disclosure: only load reference files as you need them. The entry point stays cheap.