Setup

Purpose

Guide developers through project setup and environment configuration. Discovers project structure and learns setup requirements for consistent onboarding.

When to Use

•New developer onboarding
•Setting up a new environment file
•Adding a new project configuration
•Troubleshooting setup issues

Modes

Mode	Trigger	Purpose
configure	`/setup configure`	Auto-detect project type, prerequisites, setup commands
learn	`/setup learn`	Confirm and cache setup configuration
guide	`/setup`	Guide through setup steps (default)
verify	`/setup verify`	Verify setup is complete and working

Configure Mode

Auto-detect project setup requirements:

code

/setup configure

Detects:

•Project type (Node.js, Python, Go, Rust, etc.)
•Package manager (npm, yarn, pnpm, pip, cargo, etc.)
•Prerequisites (runtime versions, tools)
•Setup commands
•Test commands
•Environment file templates

Detection sources:

File	Indicates
`package.json`	Node.js project
`pyproject.toml`, `requirements.txt`	Python project
`go.mod`	Go project
`Cargo.toml`	Rust project
`Gemfile`	Ruby project
`.env.example`	Environment template exists
`Taskfile.yaml`	Task runner available
`Makefile`	Make-based setup

Learn Mode

Confirm discovered configuration and save:

code

/setup learn

Outputs: .claude/setup-cache.yaml

yaml

# Setup configuration cache
# Generated by: /setup learn

project:
  type: nodejs
  package_manager: npm

prerequisites:
  - name: node
    version: ">=18"
    check: "node --version"
    install: "brew install node"
  - name: task
    version: ">=3"
    check: "task --version"
    install: "brew install go-task/tap/go-task"

commands:
  setup: "npm install"
  test: "npm test"
  lint: "npm run lint"
  typecheck: "npx tsc --noEmit"

environment:
  template: ".env.example"
  target: ".env"
  required_vars:
    - DATABASE_URL
    - API_KEY

Guide Mode (Default)

Step-by-step setup guidance:

code

/setup

Step 1: Check Prerequisites

Verify required tools are installed:

bash

# Check each prerequisite from cache
node --version    # Node.js
task --version    # Taskfile CLI

Step 2: Install Dependencies

Run the configured setup command:

bash

# Uses SETUP_COMMAND from skills-config.env or cache
npm install
# or: pip install -r requirements.txt
# or: cargo build
# or: make setup

Step 3: Configure Environment

bash

# Copy template if exists
cp .env.example .env

# Edit with required values
# See project README for required variables

Step 4: Verify Setup

bash

# Run tests to confirm working setup
task -t .claude/Taskfile.yaml test

Verify Mode

Check setup is complete:

code

/setup verify

Checks:

•Prerequisites installed
•Dependencies installed
•Environment configured
•Tests passing

Configuration

Config Location

Config path depends on how the plugin was installed:

Plugin Scope	Config File	Git
project	`.claude/skills/setup.yaml`	Committed (shared)
local	`.claude/skills/setup.local.yaml`	Ignored (personal)
user	`.claude/skills/setup.local.yaml`	Ignored (personal)

Precedence when reading (first found wins):

•.claude/skills/setup.local.yaml
•.claude/skills/setup.yaml
•Skill defaults

Cache Location

The discovery cache is always stored at .claude/setup-cache.yaml (per-project).

Config Fields

Configured via wizard during /setup configure:

Variable	Description	Example
`SETUP_COMMAND`	Install dependencies	`npm install`
`PREREQUISITES`	Required tools	`node>=18,docker`

Quick Reference

bash

# Discover project setup requirements
/setup configure

# Learn and cache configuration
/setup learn

# Run guided setup (default)
/setup

# Verify setup is working
/setup verify

Prerequisites (Common)

Tool	Install	Verify
Node.js 18+	`brew install node`	`node --version`
Python 3.11+	`brew install python`	`python --version`
Go 1.21+	`brew install go`	`go version`
Rust	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`	`rustc --version`
Task CLI	`brew install go-task/tap/go-task`	`task --version`
Docker	`brew install --cask docker`	`docker --version`

Troubleshooting

"command not found"

Install the missing prerequisite (see table above).

"Cannot find module" / Import errors

Run the setup command:

bash

npm install  # or equivalent for your project

Environment variable errors

Copy and configure environment file:

bash

cp .env.example .env
# Edit .env with required values

Tests failing after setup

Check for missing environment variables or configuration.

Automation

See skill.yaml for patterns and procedures. See sharp-edges.yaml for common setup issues.