setup-wizard

Setup Wizard

Interactive setup for the shared Assistant Skills Python environment.

Quick Start

Run /assistant-skills-setup to start the interactive setup wizard.

Architecture

This skill is command-based - it uses the /assistant-skills-setup slash command rather than Python scripts. The command guides Claude through the setup steps interactively using AskUserQuestion for user choices.

What Gets Configured

Component	Location	Purpose
Shared venv	`~/.assistant-skills-venv/`	Python dependencies for all Assistant Skills plugins
Config file	`~/.assistant-skills/config.yaml`	Tracks setup state, installed plugins, requirement hashes
Shell function	`~/.bashrc` or `~/.zshrc`	`claude-as` wrapper to run Claude with venv

Shell Function

After setup, use claude-as instead of claude to run with Assistant Skills dependencies:

claude-as          # Start Claude with venv activated
claude-as -p "..." # Run with prompt

The function sets PATH to include the venv without globally activating it:

claude-as() {
    VIRTUAL_ENV="$HOME/.assistant-skills-venv" \
    PATH="$HOME/.assistant-skills-venv/bin:$PATH" \
    claude "$@"
}

Configuration File

The setup creates ~/.assistant-skills/config.yaml:

venv_path: ~/.assistant-skills-venv
setup_completed_at: 2025-12-30T10:00:00Z
shell_function_added: true
shell_rc_path: ~/.zshrc

installed_plugins:
  - name: assistant-skills
    path: ~/.claude/plugins/assistant-skills
    requirements_hash: a1b2c3d4

combined_requirements_hash: xyz789abc

Environment Variables

Some Assistant Skills plugins require environment variables. The setup wizard:

Reads assistant_skills.env_vars from each plugin's plugin.json
Checks which are currently set
Offers to add placeholder exports to shell RC

Example plugin.json env_vars definition:

{
  "assistant_skills": {
    "requirements": "requirements.txt",
    "env_vars": [
      {
        "name": "SPLUNK_TOKEN",
        "description": "Splunk HEC token for API access",
        "required": true
      }
    ]
  }
}

Dependency Updates

When a plugin's requirements.txt changes:

SessionStart hook detects hash mismatch
Auto-runs pip install -r requirements.txt --upgrade
Updates stored hash in config

Troubleshooting

Python not found

# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3 python3-venv

Venv creation fails

# Ensure python3-venv is installed (Linux)
sudo apt install python3-venv

# Try creating manually
python3 -m venv ~/.assistant-skills-venv

Dependencies not found in Claude session

Ensure you're using claude-as instead of claude, or manually activate:

source ~/.assistant-skills-venv/bin/activate
claude

Re-run setup

# Remove existing config and venv
rm -rf ~/.assistant-skills ~/.assistant-skills-venv

# Run setup again
/assistant-skills-setup

Related Components

Component	Location	Purpose
Setup Command	`.claude-plugin/commands/assistant-skills-setup.md`	Interactive wizard steps
SessionStart Hook	`hooks/hooks.json`	Health checks on session start
Plugin Config	`.claude-plugin/plugin.json`	`assistant_skills` schema for env vars

About this skill