Other

/wizard

First-time onboarding wizard for the golems ecosystem. Detects installed AI CLIs, configures workspace, sets up skills. Use when setting up golems for the first time, reconfiguring, or onboarding a new machine.

$ golems-cli skills install wizard

Good

99% best pass rate

87 assertions

18 evals

fixtures

Updated 2 weeks ago

Claude-powered first-time setup. Detects your environment, writes config, installs skills.

Pre-Step: Detect Execution Mode

Before starting, determine HOW the wizard is running:

CLI mode — user ran npx golems-cli wizard from a terminal. Use interactive prompts (readline).
Skill mode — user invoked /wizard or pasted an INSTALL_PROMPT.md into a Claude Code session. Use Claude's native tools (Bash for detection, Write for config, conversation for questions).

In skill mode, use the Bash tool for which checks and the Write tool for config — do NOT attempt readline prompts.

Pre-Step: Explain on Request

If the user asks "what are skills?" or seems unfamiliar with the golems ecosystem, pause and explain before proceeding:

Skills are reusable prompt templates that give Claude Code specialized capabilities. For example:

/commit — smart git commit workflow with code review

/coach — life planning, calendar management, habit tracking

/research — deep web research with structured reports

Skills are SKILL.md files installed to ~/.claude/commands/. When you type /commit in Claude Code, it reads the skill file and follows the instructions.

This wizard detects your environment, writes a config file, and installs skills so they're ready to use.

Then ask if they want to proceed.

Step 1: Check Existing Config

Before anything else, check if ~/.golems/config.json already exists:

cat ~/.golems/config.json 2>/dev/null

If config exists:

Display the current configuration to the user (reposPath, tools, features)
Ask: "You're already configured. Would you like to reconfigure (start fresh), add skills (install more), or skip (keep current settings)?"
If add skills → jump to Step 6 (skill management). If skip → exit wizard. If reconfigure → continue to Step 2.

If config does NOT exist: Continue to Step 2.

Full SKILL.md source — includes LLM directives, anti-patterns, and technical instructions stripped from the Overview tab.

Claude-powered first-time setup. Detects your environment, writes config, installs skills.

CARDINAL RULE

ALL opt-in features are OFF by default. The user must explicitly enable each one. No surprises, no unsolicited notifications, no background tasks unless the user says yes.

Pre-Step: Detect Execution Mode

Before starting, determine HOW the wizard is running:

CLI mode — user ran npx golems-cli wizard from a terminal. Use interactive prompts (readline).
Skill mode — user invoked /wizard or pasted an INSTALL_PROMPT.md into a Claude Code session. Use Claude's native tools (Bash for detection, Write for config, conversation for questions).

In skill mode, use the Bash tool for which checks and the Write tool for config — do NOT attempt readline prompts.

Pre-Step: Explain on Request

If the user asks "what are skills?" or seems unfamiliar with the golems ecosystem, pause and explain before proceeding:

Skills are reusable prompt templates that give Claude Code specialized capabilities. For example:

/commit — smart git commit workflow with code review

/coach — life planning, calendar management, habit tracking

/research — deep web research with structured reports

Skills are SKILL.md files installed to ~/.claude/commands/. When you type /commit in Claude Code, it reads the skill file and follows the instructions.

This wizard detects your environment, writes a config file, and installs skills so they're ready to use.

Then ask if they want to proceed.

Step 1: Check Existing Config

Before anything else, check if ~/.golems/config.json already exists:

cat ~/.golems/config.json 2>/dev/null

If config exists:

Display the current configuration to the user (reposPath, tools, features)
Ask: "You're already configured. Would you like to reconfigure (start fresh), add skills (install more), or skip (keep current settings)?"
If add skills → jump to Step 6 (skill management). If skip → exit wizard. If reconfigure → continue to Step 2.

If config does NOT exist: Continue to Step 2.

Step 2: Detect Environment & CLIs

Platform Detection

Detect the platform first — it affects CLI detection commands and path formats:

uname -s  # Darwin (macOS), Linux, or check for Windows
echo $TERM_PROGRAM  # vscode, iTerm.app, Apple_Terminal, etc.

macOS/Linux: Use which for CLI detection, forward-slash paths
Windows: Use where for CLI detection, accept backslash paths. Config at %USERPROFILE%\.golems\config.json

CLI Detection

Run detection for all 9 supported CLIs:

for cmd in claude cursor gemini codex kiro-cli windsurf aider copilot cline; do
  path=$(which $cmd 2>/dev/null)
  if [ -n "$path" ]; then
    echo "  $cmd : $path"
  else
    echo "  $cmd : not found"
  fi
done

Report what was found. Store detected tools and paths for config writing.

Claude Code Gate

If Claude Code is NOT detected (which claude returns nothing):

Stop the wizard flow and provide guidance:

Claude Code CLI is required for golem skills. Skills are SKILL.md files in ~/.claude/commands/ — they only work with Claude Code.

To install Claude Code:
# macOS (recommended)
brew install claude
 
# Any platform (requires Node.js)
npm install -g @anthropic-ai/claude-code
Then run this wizard again.

Do NOT proceed with config/features/skills without Claude Code. The entire skill system depends on it.

Platform Awareness

The wizard MUST understand the AI coding tool landscape and guide users accurately:

Platform	Skills work?	What wizard does
Claude Code (CLI)	Full support	Install normally
Claude Desktop	MCP only	Guide to install Claude Code, explain skills need CLI
Claude Web (claude.ai)	No skills	Explain this, guide to Claude Code install
Cursor IDE	Partial	Some skills work via Cursor rules. Explain limitations — skills are SKILL.md files, Cursor uses `.cursorrules`.
Windsurf/Cline	Varies	Check compatibility, guide accordingly. Windsurf has its own rules system. Cline uses `.clinerules`.
Copilot/Codex	Different ecosystem	Explain, suggest alternatives
VS Code + Claude extension	Depends	Check which extension, guide

Other AI Tool Guidance

If the user mentions or has non-Claude-Code tools:

Acknowledge them — don't dismiss the user's existing tools
Explain compatibility accurately:
- Cursor = IDE with .cursorrules — some skill prompts can be adapted as Cursor rules, but no native skill support
- Cline = VS Code extension with .clinerules — similar concept, different format
- Windsurf = standalone IDE with its own cascade rules system
- Aider = CLI tool with .aider.conf.yml config — not compatible
- Copilot = VS Code/IDE extension — different paradigm entirely
- Claude Desktop = has MCP support (can use brainlayer, voicelayer MCPs) but NO skill support
Clarify coexistence — Claude Code can run alongside all of these tools. Installing Claude Code doesn't remove or conflict with existing tools.
Do NOT claim full compatibility with non-Claude-Code tools, but DO mention partial compatibility where it exists (Cursor rules)

Step 3: Ask for Workspace Root

Ask the user:

"Where is your workspace root? This is the parent directory containing your project repos (e.g., ~/Gits, ~/Projects, ~/Code)."

Path handling:

Expand ~ to the user's home directory before validation
Accept paths with spaces — quote them properly in config
On Windows, accept both C:\Users\... and C:/Users/... formats

Validate the path:

ls -d "<expanded_path>" 2>/dev/null

If the path exists → accept it
If the user provides ~ alone (home directory) → warn it's unusually broad and ask if they meant a subdirectory, but accept if they confirm
If the path does NOT exist → tell the user the path is invalid and ask again
Do NOT proceed with a nonexistent path
Do NOT write config with an invalid reposPath

Step 4: Ask About Opt-In Features

Present the following features. All default to OFF. Ask the user which (if any) they want to enable:

Feature	Default	Description
`proactiveNudges`	OFF	Coach sends periodic check-ins and reminders
`nightShift`	OFF	Autonomous improvement loop runs at 3am
`telegram`	OFF	Receive notifications via Telegram bot

Example prompt:

"These features are all disabled by default. Would you like to enable any?

Proactive nudges (coach check-ins) — OFF

Night Shift (3am autonomous work) — OFF

Telegram notifications — OFF

Enter numbers to enable (e.g., '1,3') or press Enter to keep all OFF."

Step 5: Write Config

Write ~/.golems/config.json with the collected information:

mkdir -p ~/.golems

Config structure:

{
  "reposPath": "<user_workspace_path>",
  "tools": {
    "claude": "/path/from/which"
  },
  "features": {
    "proactiveNudges": false,
    "nightShift": false,
    "telegram": false
  }
}

Only include tools that were detected (skip tools with "not found")
Set feature flags based on user's opt-in choices
Use 2-space JSON indentation
On Windows, store paths with forward slashes in JSON for consistency

After writing, confirm:

"Config written to ~/.golems/config.json"

Show the written config to the user for verification.

Step 6: Install Skills

After config is written, offer to install skills:

"Would you like to install golem skills? Options:

Install all — installs all 55 skills (~30 seconds)

Install recommended — installs the most popular skills (commit, coach, github, catchup, research)

Browse — list available skills by category and pick specific ones

Skip — install skills later with npx golems-cli skills install <name>"

If user chooses Browse:

List skills grouped by category:

Development: commit, github, pr-loop, test-plan, code-review, simplify
Research: research, youtube-pipeline, call-debrief
Operations: coach, catchup, ecosystem-health, orchestrator-status
Infrastructure: 1password, railway, convex, vercel
Voice: voice-sessions
Content: video-showcase, presentation-builder

Mark already-installed skills with [installed]. Let the user pick by name or number.

Before installing any skill, check if it already exists:

ls ~/.claude/commands/<skill_name>/ 2>/dev/null

If already installed → inform the user and offer to update (re-download latest) or skip
If not installed → install via npx golems-cli skills install <skill_name>
Do NOT install a duplicate copy

After skills are installed, check if any have MCP dependencies or complementary MCP servers. Present recommendations grouped by what's needed:

Skill → MCP mapping:

Skill	Required MCP	Complement MCP	What it adds
`research`	`exa`	`brainlayer`	Web search + persistent findings storage
`coach`	—	`brainlayer`, `supabase`	Persistent memory + calendar/habits
`catchup`	`brainlayer`	—	Retrieves past work and decisions
`cmux-agents`	—	`voicelayer`	Voice I/O for agent interaction
`convex`	`supabase`	—	Database access
`voice-sessions`	`voicelayer`	—	TTS/STT for voice workflows
`ecosystem-health`	`supabase`	`brainlayer`	Health checks + stats

Before recommending:

Check .mcp.json in the workspace root to see which MCPs are already configured
Skip MCPs that are already set up
Group recommendations: "These 3 skills all benefit from brainlayer MCP"

Present recommendations:

"Some of your installed skills work better with MCP servers:

brainlayer — persistent memory for coach, catchup, research (not yet configured)

exa — web search for research (not yet configured)

supabase — already configured

Set up brainlayer and exa? (y/n)"

If user declines: Install skills anyway, note reduced functionality. Explain how to set up MCPs later with npx golems-cli mcp install <name>.

If user accepts: Configure MCPs in .mcp.json using npx golems-cli mcp install <name>.

Step 8: Per-Skill First-Time Setup

After skills are installed, check if any have a First-Time Setup section in their SKILL.md. For each skill that does:

Read the SKILL.md
If it has a "First-Time Setup" heading → run those setup steps
Report what was configured

Completion

After all steps, display a summary:

=== Golems Setup Complete ===

Config:     ~/.golems/config.json
Workspace:  ~/Gits
Tools:      claude, gemini (2 detected)
Features:   proactiveNudges: OFF, nightShift: OFF, telegram: OFF
Skills:     12 installed

Next steps:
  - Run /wizard again to reconfigure
  - Install more skills: npx golems-cli skills install <name>
  - List available skills: npx golems-cli skills list

Anti-Patterns

NEVER enable features without explicit user consent
NEVER write config with an invalid or nonexistent workspace path
NEVER overwrite existing config without asking first
NEVER install skills that are already installed without offering update/skip
NEVER skip CLI detection — always detect platform and check CLIs
NEVER assume a workspace path — always ask the user
NEVER claim golem skills work with Cline, Windsurf, Aider, or other non-Claude-Code tools
NEVER proceed with full setup if Claude Code is not installed
NEVER use Unix-only commands (which, ls -d) on Windows without adaptation
NEVER confuse Claude Code CLI with the Cline VS Code extension — they are completely different tools

Composability

This skill is invoked by:

INSTALL_PROMPT.md files (when config doesn't exist)
golems-cli wizard command
Direct /wizard slash command in Claude

It works with:

golems-cli for skill installation
Per-skill SKILL.md for first-time setup steps

Good

Best Pass Rate

99%

Opus 4.6

Assertions

3 models tested

Avg Cost / Run

$0.4193

across models

Fastest (p50)

1.7s

Haiku 4.5

Behavior Evals

Phase 2 baseline — skill quality on Claude

Behavior Baseline

Opus 4.6

99%86/87

●

Sonnet 4.6

76%66/87

◒

Haiku 4.5

70%61/87

◒

Assertion	Opus 4.6	Sonnet 4.6	Haiku 4.5	Consensus
detects-claude-only				3/3
asks-workspace-root				3/3
asks-opt-in-features				2/3
writes-minimal-config				2/3
offers-skill-install				3/3
detects-all-three-clis				1/3
asks-workspace-root				3/3
presents-features-with-defaults-off				3/3
writes-full-config				2/3
offers-skill-install				3/3
detects-existing-config				1/3
displays-current-config				3/3
offers-reconfigure-or-skip				3/3
does-not-overwrite-silently				3/3
validates-workspace-path				1/3
reports-invalid-path				2/3
re-asks-for-valid-path				2/3
does-not-write-invalid-config				3/3
checks-skill-existence				3/3
reports-already-installed				1/3
offers-update-or-skip				3/3
does-not-duplicate-install				2/3
detects-no-claude-code				3/3
explains-claude-code-requirement				3/3
explains-what-claude-code-is				3/3
provides-install-instructions				3/3
does-not-proceed-without-claude				3/3
detects-cursor-without-claude				2/3
explains-skill-system-requirements				3/3
mentions-partial-cursor-compatibility				3/3
offers-claude-code-install				2/3
acknowledges-cursor-coexistence				2/3
detects-windows-platform				1/3
uses-windows-paths				2/3
handles-windows-cli-detection				2/3
writes-valid-windows-config				3/3
does-not-use-unix-assumptions				3/3
detects-linux-platform				3/3
uses-linux-paths				3/3
proceeds-with-setup				3/3
writes-valid-linux-config				3/3
accepts-path-with-spaces				3/3
expands-tilde				3/3
warns-about-home-as-workspace				2/3
handles-path-quoting				3/3
validates-before-accepting				2/3
explains-per-tool-compatibility				3/3
explains-claude-code-dependency				2/3
does-not-promise-full-compatibility				2/3
explains-each-tools-system				2/3
offers-claude-code-path				2/3
detects-vscode-terminal				2/3
proceeds-normally				3/3
distinguishes-cline-from-claude				3/3
explains-where-skills-work				3/3
detects-existing-setup				2/3
lists-available-skills				3/3
shows-categories-or-grouping				3/3
marks-already-installed				3/3
supports-selective-install				2/3
explains-what-skills-are				3/3
gives-concrete-examples				2/3
explains-how-skills-work				2/3
explains-wizard-purpose				2/3
does-not-assume-knowledge				2/3
offers-to-proceed				1/3
detects-skill-mode				3/3
uses-claude-tools-for-detection				2/3
asks-via-conversation				3/3
writes-config-via-tools				3/3
completes-full-setup				2/3
detects-no-claude-code				2/3
distinguishes-desktop-from-code				2/3
explains-mcp-vs-skills				1/3
offers-claude-code-install				3/3
notes-mcp-compatibility				2/3
identifies-skill-mcp-links				2/3
recommends-missing-mcps				3/3
explains-mcp-value				2/3
asks-before-configuring				3/3
skips-already-configured				3/3
does-not-block-on-mcp				2/3
respects-decline				3/3
explains-reduced-functionality				3/3
provides-later-setup-instructions				1/3
does-not-nag				3/3
skill-still-installed				3/3

Token Usage

Opus 4.6

24,101

Sonnet 4.6

6,289

Haiku 4.5

5,050

Input tokensOutput tokens

Cost per Run

Opus 4.6

$1.1989

Sonnet 4.6

$0.0558

Haiku 4.5

$0.0032

Model	Input Tokens	Output Tokens	Cost / Run	Cost / 1K Runs
Opus 4.6	10,144	13,957	$1.1989	$1198.90
Sonnet 4.6	3,211	3,078	$0.0558	$55.80
Haiku 4.5	3,084	1,966	$0.0032	$3.20

Response Time (p50)

Haiku 4.5

1.7s

Sonnet 4.6

1.9s

Opus 4.6

10.4s

Response Time (p95)

Haiku 4.5

3.1s

Sonnet 4.6

3.8s

Opus 4.6

16.0s

Model	p50	p95	Overhead
Opus 4.6	10.4s	16.0s	+53%
Sonnet 4.6	1.9s	3.8s	+99%
Haiku 4.5	1.7s	3.1s	+78%

Last evaluated: 2026-03-12 · Data is generated from skill assertions (real cross-model benchmarks coming soon)

Pre-Step: Detect Execution Mode

Pre-Step: Explain on Request

Step 1: Check Existing Config

CARDINAL RULE

Pre-Step: Detect Execution Mode

Pre-Step: Explain on Request

Step 1: Check Existing Config

Step 2: Detect Environment & CLIs

Platform Detection

CLI Detection

Claude Code Gate

Platform Awareness

Other AI Tool Guidance

Step 3: Ask for Workspace Root

Step 4: Ask About Opt-In Features

Step 5: Write Config

Step 6: Install Skills

Step 7: Recommend Complementary MCPs

Step 8: Per-Skill First-Time Setup

Completion

Anti-Patterns

Composability

Behavior Evals

Token Usage

Cost per Run

Response Time (p50)

Response Time (p95)