Skip to content

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.

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

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

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

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:

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

Or if you don't have npm:

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

Detailed Instructions

See the full Claude Code Quickstart Guide for your specific platform.

Verification

Run the following command to verify installation: 

1
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: 
    1
    claude
  3. Once Claude Code starts, type: 
    1
    /login
  4. Follow the prompts to authenticate with your Claude account

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):

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

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.

Verification

1
brew --version
You should see a version number like Homebrew 4.x.x.

For Windows Users (WSL)

  1. Open PowerShell as Administrator
  2. Run: 
    1
    wsl --install
  3. Restart your computer
  4. Open "Ubuntu" from the Start menu
  5. Create a username and password when prompted

Verification

Open Ubuntu and run: 

1
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: 

1
brew install gh

For Ubuntu/Debian/WSL: 

1
2
sudo apt update
sudo apt install gh

Verification

1
gh --version
You should see output like gh version 2.x.x.

Step 8: Authenticate GitHub CLI

  1. Run the authentication command: 
    1
    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

Verification

1
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:

1
2
mkdir -p ~/projects
cd ~/projects

Verification

1
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:

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

Verification

1
ls ~/projects
You should see my-intelligent-book listed.

Step 11: Clone the Claude Skills Repository

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

Verification

1
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): 

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

For Linux/WSL (bash): 

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

Now reload your shell configuration:

For macOS: 

1
source ~/.zshrc

For Linux/WSL: 

1
source ~/.bashrc

Verification

1
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

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

Verification

1
which bk
Should display a path like /Users/YOUR_USERNAME/.local/bin/bk.

Step 14: Install the Claude Skills

1
./scripts/bk-install-skills

Verification

1
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:

1
bk-install-mkdocs

This May Take Several Minutes

The script creates a Conda environment and installs all required Python packages.

Verification

1
2
conda activate mkdocs
mkdocs --version
Should display something like mkdocs, version 1.x.x.

Step 16: Initialize Your Book

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

This creates the basic MkDocs structure with:

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

Verification

1
ls
You should see mkdocs.yml and a docs directory.

Step 17: Commit and Push Your Changes

1
2
3
4
git status
git add .
git commit -m "Initial MkDocs setup"
git push

Verification

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

Step 18: Deploy to GitHub Pages

1
mkdocs gh-deploy

This builds your site and deploys it to GitHub Pages.

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

Verification

Your book should be visible at: 

1
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:

1
ls ~/.claude/skills

You should see output similar to:

1
2
3
4
5
6
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

Expected Result

You should see approximately 15-20 skill directories listed.

Test 2: Verify the bk Command

Run the book utilities menu:

1
bk

You should see a menu like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
════════════════════════════════════════════════════════════════
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
   ...
════════════════════════════════════════════════════════════════

Expected Result

The menu should display with BK_HOME pointing to your claude-skills directory.

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:

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

Replace YOUR_USERNAME with your actual GitHub username.

Expected Result

You should see your MkDocs site with a default homepage.

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

1
2
cd ~/projects/my-intelligent-book
claude

Test 5: Ask About Available Skills

Once Claude Code starts, type:

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

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:

1
/skills

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)

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!