/install — Setup & Health Check

Verify your Claude Code Toolkit installation, diagnose issues, and get oriented.

When to Use

After cloning the repo and running
```
install.sh
```
When something seems broken (hooks not firing, missing commands)
First time using the toolkit — to see what's available
After a
```
git pull
```
to verify nothing broke

Instructions

Phase 1: DIAGNOSE

Goal: Run deterministic health checks and report results.

Step 1: Run install-doctor.py

bash

python3 ~/.claude/scripts/install-doctor.py check

If the script is not found at

scripts/install-doctor.py

, try

~/.claude/scripts/install-doctor.py

Step 2: Interpret results

Result	Action
All checks pass	Skip to Phase 3 (Inventory)
`~/.claude` missing	Guide user to run `install.sh` — go to Phase 2
Components missing	Guide user to run `install.sh` — go to Phase 2
Hooks not configured	Guide user to run `install.sh` — go to Phase 2
Broken symlinks	Symlink targets moved. Re-run `install.sh --symlink --force`
Python deps missing	Run `pip install -r requirements.txt` from the repo directory
Permissions wrong	Run `chmod 755` on affected files

Step 3: Display results clearly

Show the check output to the user with a clear pass/fail summary. Use the raw script output — do not paraphrase or reformat excessively.

Gate: Health check complete. If issues found, proceed to Phase 2. If clean, skip to Phase 3.

Phase 2: FIX (only if issues found)

Goal: Guide the user through fixing detected issues.

Important: This phase is interactive. Show the user what needs fixing and let them choose.

Step 1: Determine if install.sh needs to run

~/.claude

is missing or components are not installed, the user needs to run install.sh. Tell them:

The toolkit hasn't been installed yet. Run this from the repo directory:

  ./install.sh --symlink     # recommended: updates with git pull
  ./install.sh --dry-run     # preview first

Wait for the user to confirm they've run it, then re-run the health check.

Step 2: Fix individual issues

For fixable issues (permissions, missing deps), offer to fix them:

bash

# Fix permissions
find ~/.claude/hooks -name "*.py" -exec chmod 755 {} \;
find ~/.claude/scripts -name "*.py" -exec chmod 755 {} \;

# Install Python deps (from repo directory)
pip install -r requirements.txt

Only run fixes the user approves.

Step 3: Re-check

After fixes, re-run:

bash

python3 ~/.claude/scripts/install-doctor.py check

Gate: All checks pass. Proceed to Phase 3.

Phase 3: INVENTORY

Goal: Show the user what they have installed.

Step 1: Run inventory

bash

python3 ~/.claude/scripts/install-doctor.py inventory

Step 2: Display summary

Show the actual counts returned by

install-doctor.py inventory

— do not display hardcoded numbers. Present them as:

Your toolkit is ready. Here's what's installed:

  Agents:   [N] specialized domain experts
  Skills:   [N] workflow methodologies ([N] user-invocable)
  Hooks:    [N] automation hooks
  Commands: [N] slash commands
  Scripts:  [N] utility scripts

Gate: User sees their inventory. Proceed to Phase 3.5.

Phase 3.5: MCP INVENTORY

Goal: Show which MCP servers are available and their status.

Step 1: Run MCP registry check

bash

python3 ~/.claude/scripts/mcp-registry.py list

If the script is not found at

scripts/mcp-registry.py

, try

~/.claude/scripts/mcp-registry.py

Step 2: Display MCP status

Show the MCP inventory as:

MCP Servers:

  [✓] Chrome DevTools MCP  — Live browser debugging
      Paired skills: wordpress-live-validation
  [✓] Playwright MCP       — Automated browser testing
      Paired skills: wordpress-live-validation
  [✓] gopls MCP            — Go workspace intelligence
      Paired skills: go-code-review, go-testing, go-concurrency
  [✗] Context7 MCP         — Library documentation lookups
      Install: claude mcp add context7 -- npx @anthropic-ai/mcp-context7@latest

Use ✓ for connected MCPs and ✗ for missing ones. For missing MCPs, show the install command.

Gate: MCP inventory displayed. Proceed to Phase 4.

Phase 4: ORIENT

Goal: Give the user their bearings — what to do first.

Step 1: Show the three essential commands

Getting started:

  /do [describe what you want]    — routes to the right agent + skill
  /comprehensive-review           — 20+ reviewer agents in 3 waves
  /install                        — run this again anytime to check health

Step 2: Show a few practical examples

Try these:

  /do debug this failing test
  /do review my Go code for quality
  /do write a blog post about [topic]
  /do create a voice profile from my writing samples

Step 3: Mention the docs

Documentation:
  docs/QUICKSTART.md   — 30-second overview
  docs/REFERENCE.md    — quick reference card

Gate: User is oriented. Installation complete.

Error Handling

Error: install-doctor.py not found

The script hasn't been installed yet. Check if the user is in the repo directory. If so, run it directly from

scripts/

. If not, guide them to clone and install first.

Error: Permission denied on install.sh

Run

chmod +x install.sh

first.

Error: Python not found

The toolkit requires Python 3.10+. Guide the user to install Python for their platform.

install

NPX Install

Tags

SKILL.md Content

/install — Setup & Health Check

When to Use

Instructions

Phase 1: DIAGNOSE

Phase 2: FIX (only if issues found)

Phase 3: INVENTORY

Phase 3.5: MCP INVENTORY

Phase 4: ORIENT

Error Handling

Error: install-doctor.py not found

Error: Permission denied on install.sh

Error: Python not found