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

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:

1. Reads assistantskills.envvars from each plugin's plugin.json
2. Checks which are currently set
3. 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:

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

Troubleshooting

Python not found

# macOS
brew install [email protected]

# 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

Related Documentation

• [Reference Guide](docs/reference.md) - Detailed schemas and troubleshooting