Development Tools, Version Control, and Deployment

Development Tools, Version Control, and Deployment

Summary

This final chapter brings together all the tools and techniques needed to complete and deploy your intelligent textbook project. You'll learn to use Visual Studio Code effectively for content development, including working with the integrated terminal. The chapter covers Bash shell scripting, script execution permissions, and essential command-line operations including directory navigation, file creation and editing, and symlink creation for skill installation.

The chapter synthesizes all the skills, tools, and knowledge from previous chapters as you work through the capstone project: creating a complete intelligent textbook from start to finish. This culminating experience demonstrates your ability to apply course description development, learning graph generation, content creation, interactive element integration, and deployment workflows to produce a professional, AI-enhanced educational resource.

Concepts Covered

This chapter covers the following 10 concepts from the learning graph:

1. Visual Studio Code
2. VS Code for Content Development
3. Terminal in VS Code
4. Bash
5. Shell Scripts
6. Script Execution Permissions
7. Directory Navigation
8. File Creation and Editing
9. Symlink Creation
10. Capstone: Complete Textbook Project

Prerequisites

This chapter builds on concepts from:

• Chapter 1: Introduction to AI and Intelligent Textbooks
• Chapter 2: Getting Started with Claude and Skills
• Chapter 4: Introduction to Learning Graphs
• Chapter 10: Content Creation Workflows
• Chapter 11: Educational Resources and Assessment
• Chapter 12: Interactive Elements and MicroSims

Introduction

Creating intelligent textbooks requires mastery of professional development tools and workflows that streamline content creation, version control, and deployment. This chapter introduces the essential development environment used throughout the intelligent textbook creation process, focusing on Visual Studio Code as the primary content authoring platform and Bash shell scripting for automation.

Unlike traditional textbook authoring tools like Microsoft Word or Google Docs, intelligent textbook development leverages software engineering practices including version control with Git, command-line workflows, and automated deployment pipelines. These practices enable collaborative content development, reproducible builds, and seamless publication to web platforms like GitHub Pages.

By the end of this chapter, you'll work through a comprehensive capstone project that integrates all the skills, tools, and workflows from previous chapters to create a complete intelligent textbook from concept to deployment.

Visual Studio Code

Visual Studio Code (VS Code) is a free, open-source code editor developed by Microsoft that has become the de facto standard for modern software development and technical content creation. While it was initially designed for programming, its extensibility, integrated terminal, and markdown preview capabilities make it ideal for intelligent textbook authoring.

Why VS Code for Textbook Development?

Traditional word processors are optimized for print documents with fixed page layouts, while intelligent textbooks are dynamic, web-based resources built from markdown source files. VS Code provides several advantages for this workflow:

• Markdown editing with live preview: Real-time rendering of formatted content
• Integrated Git support: Version control operations without leaving the editor
• Built-in terminal: Execute MkDocs commands, Python scripts, and shell utilities
• Extension ecosystem: Plugins for spell-checking, markdown linting, and diagram generation
• Multi-file management: Navigate complex textbook structures with hundreds of files
• Search and replace across files: Consistent terminology and formatting at scale

Key Features for Content Creators

The following features are particularly valuable for intelligent textbook development:

• Explorer panel: Navigate chapter directories, MicroSim folders, and asset files
• Search panel: Find all references to specific concepts across the entire textbook
• Source control panel: Track changes, create commits, and push updates to GitHub
• Extensions marketplace: Install tools like Markdown All in One, Code Spell Checker, and MkDocs plugins
• Integrated terminal: Run mkdocs serve, execute Python scripts, and manage dependencies
• Command palette (Cmd/Ctrl+Shift+P): Quick access to all VS Code functionality

Diagram: VS Code Interface Layout for Textbook Development

Purpose: Show the VS Code interface configured for intelligent textbook authoring

Components to show:
- Activity Bar (far left): Explorer, Search, Source Control, Extensions icons highlighted
- Side Bar (left): Explorer panel showing typical textbook directory structure:
  /docs
    /chapters
      /01-intro-ai-intelligent-textbooks
      /02-getting-started-claude-skills
      (etc.)
    /sims
    /learning-graph
    mkdocs.yml
- Editor Group (center): Split view showing:
  - Left pane: index.md file in edit mode with markdown content
  - Right pane: Markdown preview pane showing rendered content
- Panel (bottom): Integrated terminal showing "mkdocs serve" command running
- Status Bar (bottom): Git branch indicator, file type, cursor position

Annotations:
- Arrow pointing to Explorer: "Navigate textbook structure"
- Arrow pointing to Split editor: "Edit and preview simultaneously"
- Arrow pointing to Terminal: "Run MkDocs and Python scripts"
- Arrow pointing to Source Control icon: "Track changes with Git"

Visual style: Modern interface mockup with realistic VS Code color scheme (dark theme)
Color scheme: VS Code Dark+ theme colors (dark gray background, syntax highlighting)

Implementation: SVG diagram or annotated screenshot

MicroSim Generator Recommendations:

1. markdown/screenshot (best) - VS Code interface doesn't benefit from interactivity, annotated image clearest
2. microsim-p5 (80/100) - If interactive tour/highlighting needed, p5.js with hover zones works
3. mermaid-generator (50/100) - Not designed for UI interface mockups or screenshots

Installation and Setup

VS Code can be downloaded from code.visualstudio.com for macOS, Windows, and Linux. For intelligent textbook development, install these recommended extensions:

After installation, configure VS Code for optimal markdown editing by adding these settings to your user settings (Cmd/Ctrl+,):

{
  "editor.wordWrap": "on",
  "editor.formatOnSave": true,
  "markdown.preview.breaks": true,
  "files.trimTrailingWhitespace": true
}

VS Code for Content Development

While VS Code is a powerful general-purpose editor, intelligent textbook content development requires specific workflows and practices that differ from traditional software development. This section covers techniques for efficiently authoring markdown content, managing chapter files, and integrating with the MkDocs build system.

Content Authoring Workflow

A typical content development session follows this pattern:

1. Open the project folder: Use File → Open Folder to load the entire textbook repository
2. Start the development server: Open integrated terminal and run mkdocs serve
3. Navigate to target chapter: Use Explorer panel to locate the chapter's index.md file
4. Edit in split view: Open markdown preview (Cmd/Ctrl+K V) to see rendered output
5. Save frequently: VS Code auto-saves, but Cmd/Ctrl+S forces immediate update
6. Preview in browser: Navigate to http://localhost:8000 to see the full site

This workflow enables rapid iteration, where changes to markdown files are immediately reflected in the browser preview within 1-2 seconds of saving.

Multi-File Editing Techniques

Intelligent textbooks often require editing multiple files simultaneously—for example, updating a concept definition in the glossary while editing chapter content. VS Code provides several techniques for efficient multi-file editing:

• Split editor groups: Drag tabs to create side-by-side or stacked editor layouts
• Quick Open (Cmd/Ctrl+P): Type partial filename to instantly open any file
• Go to Symbol (Cmd/Ctrl+Shift+O): Navigate to specific headers within long markdown files
• Breadcrumbs: Show file path and document structure at top of editor
• Tab groups: Organize related files (e.g., all Chapter 3 materials) in separate tab groups

For complex editing tasks like renaming a concept across all chapters, use VS Code's search and replace across files feature:

• Open Search panel (Cmd/Ctrl+Shift+F)
• Enter search term: "Configuration Item (CI)"
• Enter replacement: "Configuration Item"
• Review matches in context
• Replace All to update all instances

Markdown Productivity Tips

The following keyboard shortcuts and features accelerate markdown authoring:

• Cmd/Ctrl+B: Toggle bold formatting on selected text
• Cmd/Ctrl+I: Toggle italic formatting
• Cmd/Ctrl+Shift+V: Open markdown preview in new tab
• Cmd/Ctrl+K V: Open preview to the side
• Alt+Shift+F: Auto-format current markdown file
• Cmd/Ctrl+/: Toggle comment on selected lines (useful for temporary removal)

The Markdown All in One extension adds additional shortcuts:

• Cmd/Ctrl+Shift+]: Insert/update table of contents
• Alt+C: Check/uncheck task list items
• Ctrl+Shift+[: Decrease heading level
• Ctrl+Shift+]: Increase heading level

Terminal in VS Code

The integrated terminal in VS Code eliminates context switching between the editor and a separate terminal application, enabling seamless execution of build commands, Python scripts, and Git operations. This integration is particularly valuable for intelligent textbook workflows where content editing and script execution are tightly coupled.

Accessing the Integrated Terminal

The terminal can be opened in several ways:

• Keyboard shortcut: Ctrl+` (backtick) toggles terminal visibility
• Menu: View → Terminal
• Command Palette: Cmd/Ctrl+Shift+P, then type "Terminal: Create New Integrated Terminal"

By default, the terminal appears in the Panel area at the bottom of the VS Code window, but it can be moved to the side or floated as a separate panel.

Terminal Features for Textbook Development

The integrated terminal provides several advantages over standalone terminal applications:

• Automatic working directory: Terminal opens in the project root directory
• Output linking: Click file paths in error messages to jump to that file
• Split terminals: Run multiple commands simultaneously (e.g., mkdocs serve in one, Python scripts in another)
• Command history: Use up/down arrows to recall previous commands
• Copy/paste integration: Cmd/Ctrl+C/V work as expected (no special terminal shortcuts needed)

Common Terminal Commands for Textbook Projects

The following commands are executed frequently during intelligent textbook development:

Managing Multiple Terminal Sessions

Complex workflows often require multiple simultaneous terminal sessions. VS Code supports this through terminal splitting and tabs:

• Create new terminal: Click + icon in terminal toolbar
• Split terminal: Click split icon to create side-by-side terminals
• Rename terminal: Right-click terminal tab, select "Rename"
• Kill terminal: Click trash icon or exit the shell process

A typical intelligent textbook development session might maintain three terminal sessions:

1. Development server terminal: Running mkdocs serve continuously
2. Script execution terminal: For running Python analysis scripts and skill invocations
3. Git operations terminal: For staging commits and pushing changes

Diagram: Terminal Workflow for Textbook Development

Purpose: Illustrate the typical terminal command sequence for developing and deploying textbook content

Visual style: Flowchart with terminal command boxes and decision points

Steps:
1. Start: "Open project in VS Code"
   Hover text: "File → Open Folder, select textbook repository"

2. Process: "Open integrated terminal (Ctrl+`)"
   Hover text: "Terminal opens in project root directory"

3. Process: "mkdocs serve"
   Hover text: "Starts development server on localhost:8000"

4. Decision: "Need to run Python scripts?"
   Hover text: "Learning graph analysis, content generation, etc."

5a. Process: "Create new terminal (+)"
    Hover text: "Keep mkdocs serve running in first terminal"

5b. Continue to step 6

6. Process: "Edit markdown files"
   Hover text: "Changes auto-reload in browser within 1-2 seconds"

7. Process: "python docs/learning-graph/analyze-graph.py"
   Hover text: "Validate learning graph quality and structure"

8. Decision: "Quality check passed?"
   Hover text: "Review quality-metrics.md for issues"

9a. Process: "Fix identified issues"
    Hover text: "Edit learning-graph.csv, re-run analysis"
    Returns to step 6

9b. Continue to step 10

10. Process: "git add . && git commit -m 'message'"
    Hover text: "Stage all changes and create commit"

11. Process: "git push origin main"
    Hover text: "Push commits to GitHub repository"

12. Process: "mkdocs gh-deploy"
    Hover text: "Build site and deploy to GitHub Pages"

13. End: "Textbook published"
    Hover text: "Changes live at https://username.github.io/textbook-name"

Color coding:
- Blue: Terminal commands
- Yellow: Decision points
- Green: Git operations
- Orange: Deployment steps

Swimlanes:
- Terminal 1 (Development Server)
- Terminal 2 (Script Execution)
- Terminal 3 (Git Operations)

Implementation: SVG flowchart with interactive hover states (HTML/CSS/JavaScript)

MicroSim Generator Recommendations:

1. mermaid-generator (95/100) - Terminal command workflow with sequential steps is ideal flowchart
2. microsim-p5 (73/100) - Custom workflow with interactive command highlighting possible
3. vis-network (55/100) - Can model workflow as graph but less intuitive than flowchart

Bash

Bash (Bourne Again Shell) is the default command-line shell on macOS and most Linux distributions, providing a text-based interface for executing commands, running scripts, and automating workflows. While Windows uses PowerShell by default, Windows Subsystem for Linux (WSL) provides access to Bash on Windows systems.

Understanding Bash is essential for intelligent textbook development because the MkDocs build system, Python script execution, Git version control, and deployment automation all rely on command-line operations.

Shell vs. Terminal vs. Bash

These terms are often used interchangeably but have distinct meanings:

• Terminal: The application that provides a text interface (e.g., Terminal.app on macOS, Windows Terminal)
• Shell: The program that interprets commands (e.g., Bash, Zsh, Fish, PowerShell)
• Bash: A specific shell implementation, currently the most widely used on Unix-like systems

When you open the integrated terminal in VS Code, you're opening a terminal application that runs a shell (typically Bash or Zsh on macOS/Linux, PowerShell on Windows).

Bash Command Structure

Bash commands follow a consistent structure:

command [options] [arguments]

For example, the command ls -la /docs/chapters breaks down as:

• Command: ls (list directory contents)
• Options: -la (long format, show hidden files)
• Arguments: /docs/chapters (directory to list)

Options typically start with - (single dash) for short options or -- (double dash) for long options. Multiple short options can be combined: -l -a is equivalent to -la.

Essential Bash Commands for Textbook Development

The following commands are used frequently in intelligent textbook workflows:

Bash Environment and Variables

Bash maintains environment variables that configure shell behavior and store system information. Common variables include:

• $HOME: User's home directory (e.g., /Users/username)
• $PATH: Directories searched for executable commands
• $PWD: Current working directory
• $USER: Current username

You can display variable values using echo:

echo $HOME      # /Users/username
echo $PATH      # /usr/local/bin:/usr/bin:/bin
echo $PWD       # /Users/username/textbook-project

Command Chaining and Redirection

Bash allows combining multiple commands using operators:

• Sequential execution (;): Run commands one after another regardless of success

  cd docs/learning-graph; python analyze-graph.py learning-graph.csv quality-metrics.md
  

• Conditional execution (&&): Run second command only if first succeeds

  mkdocs build --strict && mkdocs gh-deploy
  

• Output redirection (>): Save command output to file

  python analyze-graph.py learning-graph.csv > quality-report.txt
  

• Append to file (>>): Add command output to end of existing file

  echo "Quality check completed" >> build-log.txt
  

• Pipe (|): Send output of one command as input to another

  ls -la | grep ".md"     # List only markdown files
  

Directory Navigation

Efficient directory navigation is fundamental to command-line workflows, enabling quick access to chapter files, MicroSim directories, Python scripts, and configuration files. While graphical file browsers are intuitive, command-line navigation is often faster for developers who have memorized their project structure.

Understanding File Paths

File paths specify the location of files and directories in the filesystem hierarchy. There are two types of paths:

• Absolute paths: Start from the root directory (/ on Unix, C:\ on Windows)

  /Users/username/Documents/textbook-project/docs/chapters/01-intro/index.md
  

• Relative paths: Start from the current working directory

  # If current directory is /Users/username/Documents/textbook-project
  docs/chapters/01-intro/index.md
  

Special directory references:

• . (single dot): Current directory
• .. (double dot): Parent directory
• ~ (tilde): User's home directory
• - (dash): Previous working directory

Navigating the Filesystem

The cd (change directory) command moves between directories:

# Navigate to home directory
cd ~

# Navigate to specific project directory
cd ~/Documents/textbook-project

# Navigate to subdirectory (relative path)
cd docs/chapters

# Go up one level to parent directory
cd ..

# Go up two levels
cd ../..

# Return to previous directory
cd -

# Navigate to root directory
cd /

Intelligent Textbook Directory Structure

A typical intelligent textbook project has this structure:

textbook-project/
├── docs/
│   ├── chapters/
│   │   ├── 01-intro-ai-intelligent-textbooks/
│   │   │   └── index.md
│   │   ├── 02-getting-started-claude-skills/
│   │   │   └── index.md
│   │   └── (more chapters...)
│   ├── sims/
│   │   ├── graph-traversal/
│   │   │   ├── main.html
│   │   │   └── index.md
│   │   └── (more MicroSims...)
│   ├── learning-graph/
│   │   ├── learning-graph.csv
│   │   ├── learning-graph.json
│   │   ├── analyze-graph.py
│   │   └── quality-metrics.md
│   ├── glossary.md
│   ├── faq.md
│   └── index.md
├── scripts/
│   ├── install-claude-skills.sh
│   └── list-skills.sh
├── .claude/
│   ├── skills/
│   └── commands/
├── mkdocs.yml
├── README.md
└── requirements.txt

Navigation Best Practices

Efficient navigation requires understanding project structure and using shortcuts:

• Use tab completion: Type first few characters and press Tab to autocomplete

  cd docs/ch<Tab>     # Autocompletes to docs/chapters/
  

• Use wildcards for pattern matching:

  ls docs/chapters/*/index.md     # List all chapter index files
  

• Create shell aliases for frequent destinations:

  alias chapters="cd ~/Documents/textbook-project/docs/chapters"
  alias sims="cd ~/Documents/textbook-project/docs/sims"
  

• Use pushd and popd for temporary directory changes:

  pushd docs/learning-graph    # Navigate and save previous location
  python analyze-graph.py learning-graph.csv quality-metrics.md
  popd                         # Return to previous location
  

Diagram: Interactive Directory Navigation Practice MicroSim

Learning objective: Practice Bash directory navigation commands in a simulated filesystem without risk of breaking a real project

Canvas layout (900x700px):
- Left side (550x700): Simulated terminal interface showing:
  - Current working directory display at top
  - Command input field
  - Command output area
  - Command history (last 5 commands)
- Right side (350x700): Visual filesystem tree showing:
  - Root directory
  - Expandable/collapsible directories
  - Current location highlighted in yellow
  - Files shown as leaf nodes

Visual elements:
- Terminal with black background, green text (retro style)
- Filesystem tree with folder icons (📁) and file icons (📄)
- Current directory highlighted with yellow background
- Valid commands show success in green, errors in red
- Breadcrumb trail showing path to current location

Simulated filesystem structure:
```
/home/student/
├── textbook-project/
│   ├── docs/
│   │   ├── chapters/
│   │   │   ├── 01-intro/
│   │   │   │   └── index.md
│   │   │   └── 02-graphs/
│   │   │       └── index.md
│   │   ├── sims/
│   │   │   └── graph-viz/
│   │   │       └── main.html
│   │   └── learning-graph/
│   │       ├── learning-graph.csv
│   │       └── analyze-graph.py
│   ├── scripts/
│   │   └── install-skills.sh
│   └── mkdocs.yml
└── Downloads/
    └── readme.txt
```

Interactive controls (right panel):
- Display: Current working directory (e.g., "/home/student")
- Text input: Command entry field
- Button: "Execute Command"
- Button: "Clear Terminal"
- Button: "Reset to Home"
- Checkbox: "Show hidden files"
- Display: Challenge progress (5 challenges)

Supported commands:
- `pwd`: Display current directory
- `ls`: List current directory contents
- `ls -la`: List with details
- `cd <directory>`: Change to specified directory
- `cd ..`: Go to parent directory
- `cd ~`: Go to home directory
- `cd -`: Go to previous directory

Default parameters:
- Starting directory: /home/student
- Challenge mode: Enabled
- Show hints: True

Challenges (progressively harder):
1. "Navigate to the textbook-project directory"
   Solution: `cd textbook-project`
2. "List the contents of the docs directory without changing into it"
   Solution: `ls docs`
3. "Navigate to the chapters directory using a relative path"
   Solution: `cd docs/chapters`
4. "Navigate to the scripts directory from chapters"
   Solution: `cd ../../scripts`
5. "Return to the previous directory using the dash shortcut"
   Solution: `cd -`

Behavior:
- When user enters command, parse and validate it
- If valid, update current directory and filesystem tree highlight
- Display command output in terminal area
- Show error message for invalid commands
- Track challenge completion (green checkmark when solved)
- Provide hint button that shows first step of current challenge

Interactive features:
- Click directories in tree view to highlight them (doesn't navigate)
- Hover over directories shows full path
- Right-click file/directory shows properties (size, permissions)
- Double-click directory in tree auto-fills `cd` command

Feedback:
- Success messages: "✓ Navigated to /home/student/textbook-project"
- Error messages: "✗ Directory not found: 'doc' (did you mean 'docs'?)"
- Challenge completion: "🎉 Challenge 1 complete! (4 remaining)"
- Hints: "💡 Hint: Try using 'cd' followed by the directory name"

Implementation notes:
- Use p5.js for rendering
- Store filesystem as nested JavaScript object
- Track current working directory as array of path segments
- Parse commands using string splitting and regex
- Implement basic tab completion (suggest directory names)
- Save progress to localStorage for session persistence

MicroSim Generator Recommendations:

1. microsim-p5 (94/100) - Interactive directory navigation simulator with terminal emulation is p5.js strength
2. vis-network (85/100) - Can show filesystem as interactive tree graph with navigation
3. mermaid-generator (78/100) - Tree diagram for filesystem but limited interactivity

File Creation and Editing

Command-line file creation and editing are essential skills for automating textbook workflows, especially when generating multiple files from templates or making bulk updates. While VS Code is the primary editor for content development, knowing command-line file operations enables scripting and automation.

Creating Files

The touch command creates empty files or updates the modification timestamp of existing files:

# Create a new chapter index file
touch docs/chapters/14-future-directions/index.md

# Create multiple files at once
touch docs/chapters/14-future-directions/{index.md,exercises.md,glossary.md}

The echo command combined with output redirection creates files with initial content:

# Create file with single line of content
echo "# Chapter 14: Future Directions" > docs/chapters/14-future-directions/index.md

# Append content to existing file
echo "## Summary" >> docs/chapters/14-future-directions/index.md

For multi-line content, use a here-document:

cat << EOF > docs/chapters/14-future-directions/index.md
# Chapter 14: Future Directions

## Summary

This chapter explores emerging trends in AI-assisted education.

## Concepts Covered

1. Large Language Models
2. Adaptive Learning Systems
3. Real-time Content Generation
EOF

Editing Files

While command-line text editors like vim, nano, and emacs are available, most intelligent textbook developers prefer editing in VS Code. However, simple text transformations can be performed using command-line tools:

sed (stream editor): Perform find-and-replace operations

# Replace all occurrences of "CMDB" with "Configuration Management Database"
sed -i '' 's/CMDB/Configuration Management Database/g' docs/chapters/*/index.md

# Add a line after a specific pattern
sed -i '' '/## Summary/a\
This chapter covers fundamental concepts.' docs/chapters/14-future-directions/index.md

awk (text processing): Extract and transform structured text

# Extract all level-2 headers from a file
awk '/^## / {print $0}' docs/chapters/01-intro/index.md

# Print only lines containing "learning graph"
awk '/learning graph/ {print}' docs/chapters/*/index.md

grep (pattern matching): Search for text patterns

# Find all chapters mentioning "MicroSim"
grep -r "MicroSim" docs/chapters/

# Count occurrences of "learning graph" in all markdown files
grep -r "learning graph" docs/ --include="*.md" | wc -l

File Manipulation Operations

Common file operations for textbook projects:

Safe File Operations

To prevent accidental data loss, use these practices:

• Use -i flag for interactive confirmation:

  rm -i docs/chapters/draft.md    # Prompts "remove docs/chapters/draft.md?"
  

• Use -n flag for no-clobber (don't overwrite):

  cp -n source.md destination.md  # Only copies if destination doesn't exist
  

• Preview operations before executing:

  # Preview files that would be deleted
  find docs/chapters -name "draft*.md"
  # Then delete them
  find docs/chapters -name "draft*.md" -delete
  

• Use version control as a safety net:

  git status                      # Check for uncommitted changes
  git stash                       # Temporarily save current changes
  # Perform risky operations
  git stash pop                   # Restore changes if needed
  

Shell Scripts

Shell scripts are text files containing sequences of Bash commands that automate repetitive tasks. In intelligent textbook development, shell scripts are used to install Claude skills, generate content, validate quality, and deploy to production.

Anatomy of a Shell Script

A basic shell script has three components:

1. Shebang line: Specifies the interpreter (always first line)

   #!/bin/bash
   

2. Comments: Explain what the script does (start with #)

   # Install Claude skills to global skills directory
   

3. Commands: The actual operations to perform

   ln -s $(pwd)/skills/* ~/.claude/skills/
   

Example: Installing Claude Skills

The install-claude-skills.sh script creates symbolic links from the project's skills directory to the global Claude skills directory:

#!/bin/bash

# Install Claude skills to global skills directory
# This makes skills available to all Claude projects

SKILLS_DIR="$HOME/.claude/skills"
PROJECT_SKILLS="$(pwd)/skills"

# Create skills directory if it doesn't exist
mkdir -p "$SKILLS_DIR"

# Link each skill to global directory
for skill in "$PROJECT_SKILLS"/*; do
    skill_name=$(basename "$skill")
    echo "Installing skill: $skill_name"
    ln -sf "$skill" "$SKILLS_DIR/$skill_name"
done

echo "Skills installation complete!"

Script Components Explained

Variables:

SKILLS_DIR="$HOME/.claude/skills"      # Directory where skills are installed
PROJECT_SKILLS="$(pwd)/skills"         # Directory containing project skills

Command substitution:

skill_name=$(basename "$skill")        # Extracts filename from full path

For loops:

for skill in "$PROJECT_SKILLS"/*; do   # Iterate over each skill directory
    # Commands here execute for each skill
done

Conditional creation:

mkdir -p "$SKILLS_DIR"                 # Create directory if it doesn't exist

Symbolic links:

ln -sf "$skill" "$SKILLS_DIR/$skill_name"    # -s = symbolic, -f = force (replace if exists)

Script Best Practices

Effective shell scripts follow these conventions:

• Start with shebang: #!/bin/bash on line 1
• Use meaningful variable names: SKILLS_DIR not dir1
• Quote variables: "$variable" prevents word splitting
• Check for errors: Use set -e to exit on any command failure
• Add help text: Provide usage instructions when run with -h or --help
• Use functions: Break complex scripts into reusable functions
• Validate inputs: Check that required files/directories exist

Example: Advanced Script with Error Handling

#!/bin/bash
set -e  # Exit on any error

# Validate learning graph quality before deployment

LEARNING_GRAPH_CSV="docs/learning-graph/learning-graph.csv"
QUALITY_THRESHOLD=70

# Check that learning graph file exists
if [ ! -f "$LEARNING_GRAPH_CSV" ]; then
    echo "Error: Learning graph file not found: $LEARNING_GRAPH_CSV"
    exit 1
fi

# Run quality analysis
echo "Analyzing learning graph quality..."
python docs/learning-graph/analyze-graph.py "$LEARNING_GRAPH_CSV" quality-metrics.md

# Extract quality score from quality-metrics.md
quality_score=$(grep "Quality Score:" quality-metrics.md | awk '{print $3}' | cut -d'/' -f1)

echo "Quality score: $quality_score/100"

# Check if quality meets threshold
if [ "$quality_score" -lt "$QUALITY_THRESHOLD" ]; then
    echo "Error: Quality score ($quality_score) is below threshold ($QUALITY_THRESHOLD)"
    echo "Review quality-metrics.md for issues"
    exit 1
fi

echo "✓ Quality check passed! Ready for deployment."

This script demonstrates:

• Error handling with set -e
• File existence checks
• External command execution (Python script)
• Text parsing with grep, awk, and cut
• Conditional logic with if statements
• Meaningful exit codes (0 = success, 1 = failure)

Script Execution Permissions

Unix-like systems (macOS, Linux) use a permission system to control who can read, write, or execute files. Before a shell script can be run, it must have execute permissions set.

Understanding File Permissions

File permissions are displayed by ls -l:

$ ls -l scripts/install-claude-skills.sh
-rwxr-xr-x  1 username  staff  512 Jan 15 10:30 install-claude-skills.sh

The permission string -rwxr-xr-x breaks down as:

• File type: - (regular file), d (directory), l (symbolic link)
• Owner permissions: rwx (read, write, execute)
• Group permissions: r-x (read, execute, no write)
• Other permissions: r-x (read, execute, no write)

Permission Notation

Permissions can be represented in two formats:

Symbolic notation:

r = read (4)
w = write (2)
x = execute (1)

Numeric notation (octal):

rwx = 4+2+1 = 7
r-x = 4+0+1 = 5
r-- = 4+0+0 = 4

Common permission combinations:

Making Scripts Executable

To make a script executable, use the chmod command:

# Add execute permission for owner
chmod +x scripts/install-claude-skills.sh

# Add execute permission for everyone
chmod a+x scripts/install-claude-skills.sh

# Set specific permissions using numeric notation
chmod 755 scripts/install-claude-skills.sh

After setting execute permissions, the script can be run directly:

# Run with full path
./scripts/install-claude-skills.sh

# Run with relative path
cd scripts
./install-claude-skills.sh

# Run from anywhere if in PATH
install-claude-skills.sh

Diagram: Permission Bits Visual Infographic

Purpose: Explain Unix file permission system with visual representation of permission bits

Layout: Grid layout with three main sections

Section 1 - Permission String Breakdown (top):
- Large text: `-rwxr-xr-x`
- Each character highlighted separately:
  - `-` → "File type: Regular file"
  - `rwx` → "Owner: Read, Write, Execute"
  - `r-x` → "Group: Read, Execute only"
  - `r-x` → "Others: Read, Execute only"
- Color coding: Owner (blue), Group (green), Others (orange)

Section 2 - Octal Representation (middle):
- Visual breakdown showing how rwx maps to numbers:
  ```
  r w x
  4 2 1
  ```
- Example calculations:
  - rwx = 4+2+1 = 7
  - r-x = 4+0+1 = 5
  - r-- = 4+0+0 = 4
- Final octal: **755**

Section 3 - Common Permissions (bottom):
- Cards showing common permission sets:

  Card 1: "Executable Script"
  - Octal: 755
  - Symbolic: -rwxr-xr-x
  - Use case: Shell scripts that should run
  - Icon: 📜 with ⚡

  Card 2: "Private Script"
  - Octal: 700
  - Symbolic: -rwx------
  - Use case: Scripts with sensitive data
  - Icon: 🔒

  Card 3: "Markdown File"
  - Octal: 644
  - Symbolic: -rw-r--r--
  - Use case: Documentation files
  - Icon: 📝

  Card 4: "Directory"
  - Octal: 755
  - Symbolic: drwx

…(truncated)