Workshop Pre-Work

Workshop Pre-Work

Before you come to the workshop you must have Claude Code installed with all the intelligent textbook skills installed in a Claude Code skills directory. You should also have a GitHub account created and an initial GitHub repository setup with a template intelligent textbook installed in the GitHub repository. Having all these components installed before you come to our class allows us all to focus on creation of the textbook, not the installation of the software.

!!! warning "System Requirements" Claude Code is a Linux shell system. You must have one of the following:

1. A Mac running macOS
2. A PC running Linux
3. A virtual machine such as Docker running Linux
4. A Raspberry Pi
5. A Windows system running WSL (Windows Subsystem for Linux)
6. A cloud-server account running Linux

**Claude Code does not run well on native Windows.** Windows users must install WSL first.

Step 1: Create a GitHub Account

If you don't already have a GitHub account:

1. Go to https://github.com
2. Click Sign up
3. Follow the prompts to create your account
4. Verify your email address

!!! tip "Verification" You should be able to log in at https://github.com and see your dashboard.

Step 2: Create Your Book Repository

1. Log in to GitHub
2. Click the + icon in the top right corner
3. Select New repository
4. Name your repository (e.g., my-intelligent-book)
5. Select Public (required for GitHub Pages)
6. Check Add a README file
7. Click Create repository

!!! tip "Verification" Your repository should be visible at https://github.com/YOUR_USERNAME/my-intelligent-book

Step 3: Create a Claude Account

You need a Claude Pro ($20/month) or Max ($100/month) subscription to use Claude Code.

1. Go to https://claude.ai
2. Sign up or log in
3. Navigate to your account settings
4. Subscribe to Claude Pro or Max

!!! hint "Which Plan?" - Pro ($20/month): Good for learning and moderate usage - Max ($100/month): Better for heavy usage and longer conversations

Step 4: Install Claude Code

Follow the official quickstart guide to install Claude Code:

For macOS/Linux:

npm install -g @anthropic-ai/claude-code

Or if you don't have npm:

curl -fsSL https://claude.ai/install.sh | sh

!!! note "Detailed Instructions" See the full Claude Code Quickstart Guide for your specific platform.

!!! tip "Verification" Run the following command to verify installation: bash claude --version You should see a version number displayed.

Step 5: Log In to Claude Code

1. Open your terminal
2. Run the claude command:

   claude
   

3. Once Claude Code starts, type:

   /login
   

4. Follow the prompts to authenticate with your Claude account

!!! tip "Verification" After logging in, you should see a message confirming your authentication.

Step 6: Install Package Managers

For macOS Users

Install Homebrew (the macOS package manager):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

!!! warning "Admin Rights Required" You must have administrator privileges on your Mac to install Homebrew.

After installation, follow the instructions displayed to add Homebrew to your PATH.

!!! tip "Verification" bash brew --version You should see a version number like Homebrew 4.x.x.

For Windows Users (WSL)

1. Open PowerShell as Administrator
2. Run:

   wsl --install
   

3. Restart your computer
4. Open "Ubuntu" from the Start menu
5. Create a username and password when prompted

!!! tip "Verification" Open Ubuntu and run: bash lsb_release -a You should see Ubuntu version information.

Step 7: Install GitHub CLI (gh)

The GitHub CLI allows Claude Code to authenticate with your GitHub account.

For macOS:

brew install gh

For Ubuntu/Debian/WSL:

sudo apt update
sudo apt install gh

!!! tip "Verification" bash gh --version You should see output like gh version 2.x.x.

Step 8: Authenticate GitHub CLI

1. Run the authentication command:

   gh auth login
   

2. Select GitHub.com
3. Select HTTPS
4. Select Yes when asked to authenticate Git with your GitHub credentials
5. Select Login with a web browser
6. Copy the one-time code displayed
7. Press Enter to open your browser
8. Paste the code and authorize the application

!!! tip "Verification" bash gh auth status You should see: Logged in to github.com as YOUR_USERNAME

Step 9: Create Your Projects Directory

Create a directory to hold all your projects:

mkdir -p ~/projects
cd ~/projects

!!! tip "Verification" bash pwd Should display /Users/YOUR_USERNAME/projects (macOS) or /home/YOUR_USERNAME/projects (Linux/WSL).

Step 10: Clone Your Book Repository

Replace YOUR_USERNAME with your actual GitHub username:

cd ~/projects
git clone https://github.com/YOUR_USERNAME/my-intelligent-book.git

!!! tip "Verification" bash ls ~/projects You should see my-intelligent-book listed.

Step 11: Clone the Claude Skills Repository

cd ~/projects
git clone https://github.com/dmccreary/claude-skills.git

!!! tip "Verification" bash ls ~/projects You should see both my-intelligent-book and claude-skills listed.

Step 12: Configure Your Shell Environment

Add environment variables to your shell configuration file.

For macOS (zsh):

echo 'export BK_HOME="$HOME/projects/claude-skills"' >> ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

For Linux/WSL (bash):

echo 'export BK_HOME="$HOME/projects/claude-skills"' >> ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Now reload your shell configuration:

For macOS:

source ~/.zshrc

For Linux/WSL:

source ~/.bashrc

!!! tip "Verification" bash echo $BK_HOME Should display /Users/YOUR_USERNAME/projects/claude-skills or /home/YOUR_USERNAME/projects/claude-skills.

Step 13: Install the Book-Building Scripts

cd ~/projects/claude-skills
./scripts/bk-install-scripts

!!! tip "Verification" bash which bk Should display a path like /Users/YOUR_USERNAME/.local/bin/bk.

Step 14: Install the Claude Skills

./scripts/bk-install-skills

!!! tip "Verification" bash ls ~/.claude/skills You should see a list of skills including learning-graph-generator, microsim-generator, etc.

Step 15: Install MkDocs

This installs MkDocs and the Material theme using Conda:

bk-install-mkdocs

!!! note "This May Take Several Minutes" The script creates a Conda environment and installs all required Python packages.

!!! tip "Verification" bash conda activate mkdocs mkdocs --version Should display something like mkdocs, version 1.x.x.

Step 16: Initialize Your Book

cd ~/projects/my-intelligent-book
mkdocs new .

This creates the basic MkDocs structure with:

• mkdocs.yml - Configuration file
• docs/index.md - Your homepage

!!! tip "Verification" bash ls You should see mkdocs.yml and a docs directory.

Step 17: Commit and Push Your Changes

git status
git add .
git commit -m "Initial MkDocs setup"
git push

!!! tip "Verification" Go to your repository on GitHub. You should see the mkdocs.yml file and docs folder.

Step 18: Deploy to GitHub Pages

mkdocs gh-deploy

This builds your site and deploys it to GitHub Pages.

!!! warning "First Deployment" The first deployment may take a few minutes. You may also need to enable GitHub Pages in your repository settings:

1. Go to your repository on GitHub
2. Click **Settings** → **Pages**
3. Under "Source", select **Deploy from a branch**
4. Select the **gh-pages** branch
5. Click **Save**

!!! tip "Verification" Your book should be visible at: https://YOUR_USERNAME.github.io/my-intelligent-book (Replace YOUR_USERNAME with your GitHub username)

Testing Your Installation

Run through these tests to verify everything is working correctly.

Test 1: Verify Skills Are Installed

List your installed skills:

ls ~/.claude/skills

You should see output similar to:

book-chapter-generator          glossary-generator              moving-rainbow
book-metrics-generator          book-installer                  pi-keys-generator
chapter-content-generator       learning-graph-generator        quiz-generator
concept-classifier              linkedin-announcement-generator readme-generator
faq-generator                   microsim-generator              reference-generator
                                microsim-utils                  skill-creator

!!! success "Expected Result" You should see approximately 15-20 skill directories listed.

Test 2: Verify the bk Command

Run the book utilities menu:

bk

You should see a menu like this:

════════════════════════════════════════════════════════════════
Build/Book Utilities
════════════════════════════════════════════════════════════════
BK_HOME: /home/YOUR_USERNAME/projects/claude-skills

   1. bk                                  Build/Book utilities menu
   2. bk-analyze-skill-usage              Generate a comprehensive skill usage analysis...
   3. bk-batch-capture-screenshots        Batch Screenshot Capture for MicroSims
   ...
════════════════════════════════════════════════════════════════

!!! success "Expected Result" The menu should display with BK_HOME pointing to your claude-skills directory.

!!! warning "Troubleshooting" If you see command not found: bk, make sure you:

1. Ran `./scripts/bk-install-scripts` from the claude-skills directory
2. Added `$HOME/.local/bin` to your PATH
3. Reloaded your shell with `source ~/.zshrc` or `source ~/.bashrc`

Test 3: Verify Your Book Is Published

Open your browser and navigate to:

https://YOUR_USERNAME.github.io/my-intelligent-book

Replace YOUR_USERNAME with your actual GitHub username.

!!! success "Expected Result" You should see your MkDocs site with a default homepage.

!!! warning "Troubleshooting" If you see a 404 error:

1. Wait a few minutes - GitHub Pages can take time to deploy
2. Check your repository settings to ensure GitHub Pages is enabled
3. Verify the `gh-pages` branch exists in your repository

Testing Claude Code Skills

Now let's verify Claude Code can see and use your skills.

Test 4: Start Claude Code

cd ~/projects/my-intelligent-book
claude

Test 5: Ask About Available Skills

Once Claude Code starts, type:

What skills do you know about for building intelligent textbooks and MicroSims?

!!! success "Expected Result" Claude should list skills including:

- `learning-graph-generator`
- `microsim-generator`
- `chapter-content-generator`
- `glossary-generator`
- And others...

Test 6: List All Skills

You can also use the /skills command:

/skills

!!! success "Expected Result" Claude should display a formatted list of all available skills with their descriptions.

Quick Reference Checklist

Use this checklist to verify your installation is complete:

• GitHub account created and logged in
• Book repository created (my-intelligent-book)
• Claude Pro or Max subscription active
• Claude Code installed (claude --version works)
• Logged in to Claude Code (/login completed)
• Homebrew installed (macOS) or WSL installed (Windows)
• GitHub CLI installed (gh --version works)
• GitHub CLI authenticated (gh auth status shows logged in)
• Projects directory created (~/projects)
• Book repository cloned
• Claude-skills repository cloned
• Environment variables set (echo $BK_HOME shows path)
• Book scripts installed (which bk shows path)
• Claude skills installed (ls ~/.claude/skills shows skills)
• MkDocs installed (mkdocs --version works)
• Book initialized (mkdocs.yml exists)
• Changes committed and pushed to GitHub
• Book deployed to GitHub Pages (site is visible)

!!! tip "Need Help?" If you encounter issues during setup, please:

1. Take a screenshot of any error messages
2. Note which step you're on
3. Bring your questions to the workshop - we'll help you troubleshoot!

What's Next?

Once you've completed all the pre-work, you're ready for the workshop! We'll cover:

1. Creating your course description
2. Generating a learning graph
3. Building chapter structures
4. Creating interactive MicroSims
5. Publishing your intelligent textbook

See you at the workshop!