Getting Started with Claude and Skills

Getting Started with Claude and Skills

Summary

This chapter introduces the Claude Skills system, which is the foundation for automating intelligent textbook creation. You'll learn the structure of skill definition files, including YAML frontmatter, skill names, descriptions, licenses, and allowed tools. The chapter covers how to install skills, list available skills, and invoke them using slash commands. You'll also learn about Claude Commands and understand the important differences between skills and commands.

Additionally, this chapter explores practical considerations for working with Claude, including token limits, token management strategies, and iterative prompt refinement techniques that will help you work more effectively throughout the course.

Concepts Covered

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

1. Claude Skill
2. Skill Definition File Structure
3. YAML Frontmatter in Skills
4. Skill Name and Description
5. Skill License Information
6. Allowed Tools in Skills
7. Skill Workflow Instructions
8. Installing a Claude Skill
9. Listing Available Skills
10. Invoking Skills with Slash Commands
11. Skill Execution Context
12. Claude Command
13. Command Definition Files
14. Installing Claude Commands
15. Difference Between Skills & Commands
16. Iterative Prompt Refinement
17. Claude Token Limits
18. Token Management Strategies

Prerequisites

This chapter builds on concepts from:

• Chapter 1: Introduction to AI and Intelligent Textbooks

Understanding Claude Skills

Claude Skills represent autonomous agents—specialized AI assistants designed to execute complex, multi-step workflows without continuous human intervention. Unlike simple prompts that request a single output, skills encapsulate comprehensive procedures including context gathering, quality validation, iterative refinement, and structured deliverable generation.

In the context of intelligent textbook creation, skills automate domain-specific tasks such as generating learning graphs from course descriptions, creating glossaries aligned with ISO 11179 metadata standards, and producing interactive quizzes distributed across Bloom's Taxonomy cognitive levels. Each skill embodies best-practice workflows developed through iterative refinement, enabling consistent, high-quality outputs even for users new to educational content creation.

The skills framework addresses a fundamental challenge in AI-assisted content generation: translating high-level goals ("create an intelligent textbook") into executable sequences of specific operations. By packaging workflow expertise into reusable skills, the framework democratizes access to sophisticated educational content creation capabilities that would otherwise require extensive prompt engineering expertise.

!!! info "Historical Context: The Evolution to Claude Skills" Claude Skills emerged from decades of AI research and development. To understand the technological foundations that made skills possible, explore the Evolution of AI: From Neural Networks to Claude Code interactive timeline. This visualization traces 52 pivotal moments from the Perceptron (1957) through transformers, large language models, and Constitutional AI, culminating in Claude Code and the official Claude Skills announcement in October 2025.

Key milestones enabling skills:

- **1957-2011**: Neural network foundations (backpropagation, LSTM, deep learning revival)
- **2012-2016**: Computer vision breakthroughs (AlexNet, ResNet demonstrating deep learning power)
- **2017-2019**: Transformer architecture enabling language understanding at scale
- **2020-2022**: Large language models (GPT-3, ChatGPT) bringing AI to mainstream users
- **2021-2024**: Anthropic's Constitutional AI and Claude development focusing on safety
- **2024-2025**: Claude Code and Skills formalizing AI-assisted development workflows

[View Interactive Timeline](../../sims/claude-code-timeline/main.html){ .md-button }

Key distinctions between skills and general prompts:

• Workflow automation: Skills execute multi-step procedures autonomously
• Quality assurance: Built-in validation checkpoints ensure outputs meet standards
• Context management: Skills determine which files and resources to access
• Error handling: Skills adapt when expected files are missing or formats differ
• Consistency: Repeated executions produce structurally similar outputs

Skill Definition File Structure

Every Claude Skill is defined by a SKILL.md file containing both metadata (YAML frontmatter) and workflow instructions (markdown content). This standardized structure enables Claude Code to discover, load, and execute skills consistently across projects.

The canonical skill file structure follows this pattern:

---
name: skill-name-in-kebab-case
description: One-sentence summary of what the skill does
license: MIT
allowed-tools: [Tool1, Tool2, Tool3]
---

# Skill Display Name

## Overview

Brief description of the skill's purpose and when to use it.

## When to Use This Skill

Specific scenarios where this skill applies.

## Workflow

### Step 1: First Action

Detailed instructions for the first step.

### Step 2: Second Action

Detailed instructions for the second step.

## Resources

References to supporting files, templates, or documentation.

The separation of metadata (YAML frontmatter) from workflow instructions (markdown body) enables both machine parsing for skill discovery and human readability for understanding and customization. Claude Code processes the YAML to determine skill identity and tool permissions, then executes the markdown workflow instructions sequentially.

Diagram: Skill File Anatomy Diagram

Purpose: Illustrate the structure of a SKILL.md file with labeled components

Components to show:
- YAML Frontmatter section (top, enclosed in --- delimiters)
  - name field
  - description field
  - license field
  - allowed-tools field (shown as array)
- Markdown Body section (below frontmatter)
  - ## Overview heading
  - ## When to Use heading
  - ## Workflow heading with numbered steps
  - ## Resources heading
- Annotations showing what each section controls

Layout: Vertical document structure with left sidebar annotations

Labels:
- "YAML Frontmatter: Machine-readable metadata"
- "name: Identifies skill for invocation"
- "description: Used in skill listings"
- "allowed-tools: Permissions for tool access"
- "Markdown Body: Human-readable workflow"
- "Workflow section: Step-by-step execution instructions"

Visual style: Document mockup with syntax highlighting

Color scheme: Yellow background for YAML section, white for markdown body, blue annotations

Implementation: SVG diagram with code-style formatting

MicroSim Generator Recommendations:

1. microsim-p5 (Score: 90/100) - Excellent for custom document mockup with syntax highlighting, colored regions for YAML vs markdown sections, and visual annotations
2. mermaid-generator (Score: 45/100) - Could use block diagram but lacks code-style formatting and syntax highlighting capabilities
3. chartjs-generator (Score: 10/100) - Not a data visualization, cannot effectively represent document structure

YAML Frontmatter in Skills

The YAML frontmatter section provides metadata that Claude Code uses for skill discovery, permission management, and user-facing documentation. All frontmatter fields use lowercase keys and follow YAML syntax conventions.

Required frontmatter fields:

name: The skill identifier in kebab-case (lowercase with hyphens). Must be unique within the skills directory. Examples: learning-graph-generator, quiz-generator, microsim-p5

description: A concise (typically 1-3 sentences) summary of the skill's function. This appears in skill listings when users run /skills or list-skills.sh. Should clearly communicate what the skill does and when to use it.

license: The software license under which the skill is distributed. Common choices: MIT, Apache-2.0, CC-BY-4.0. For educational skills in this repository, MIT is standard.

Optional frontmatter fields:

allowed-tools: An array of tool names the skill is permitted to use. When specified, this constrains the skill to only those tools, preventing unintended file modifications or external network access. Example: [Read, Grep, Bash] for a skill that only needs to analyze existing files.

When allowed-tools is omitted, the skill has access to all tools available to Claude Code. This is appropriate for skills that need full flexibility (like the intelligent-textbook-creator skill that orchestrates multiple sub-skills), but should be avoided when narrower permissions suffice.

Skill Name and Description

Effective skill names and descriptions follow conventions that aid discoverability and communicate purpose clearly.

Naming conventions:

• Use verb-noun pattern: generate-glossary, create-microsim, analyze-quality
• Reflect the primary output: learning-graph-generator produces learning graphs
• Avoid abbreviations unless universally understood
• Keep length under 40 characters for usability in listings
• Use hyphens (kebab-case), never underscores or camelCase

Description best practices:

• Start with present-tense verb: "Generates", "Creates", "Analyzes"
• Specify primary input and output: "Generates a comprehensive glossary from learning graph concepts"
• Include key constraints or standards: "following ISO 11179 metadata registry standards"
• Mention when to use relative to other skills: "Use after learning graph has been finalized"
• Keep under 200 characters for display in skill listings

Example skill descriptions from this repository:

• learning-graph-generator: "Generates a comprehensive learning graph from a course description, including 200 concepts with dependencies, taxonomy categorization, and quality validation reports."
• glossary-generator: "Automatically generates a comprehensive glossary of terms from a learning graph's concept list, ensuring each definition follows ISO 11179 metadata registry standards."
• quiz-generator: "Generates interactive multiple-choice quizzes for each chapter with questions aligned to specific concepts and distributed across Bloom's Taxonomy cognitive levels."

Notice how each description answers: What does it make? From what input? Following what standards? This clarity enables users to select the appropriate skill for their current workflow stage.

Skill License Information

Licensing determines how skills can be shared, modified, and redistributed. For educational skills in open-source repositories, permissive licenses like MIT enable maximum adoption and customization.

The MIT License provides:

• Permission to use, copy, modify, merge, publish, distribute, sublicense, and sell
• Requirement to include copyright notice and license text in redistributions
• No warranty or liability for the licensor

For skills in this repository, the MIT license supports the educational mission by allowing instructors to adapt skills for their specific courses, students to learn from and modify the code, and developers to build derivative works.

Alternative licenses you might encounter:

• Apache 2.0: Similar to MIT but with explicit patent grant protection
• CC-BY-4.0: Creative Commons Attribution license, appropriate for documentation-heavy skills
• GPL-3.0: Copyleft license requiring derivative works to use the same license

When creating your own skills, choose licenses that align with your sharing goals. For educational contexts, permissive licenses (MIT, Apache 2.0, CC-BY) generally maximize positive impact.

Allowed Tools in Skills

The allowed-tools frontmatter field provides fine-grained permission control, limiting skills to specific Claude Code tools. This security and safety mechanism prevents skills from performing unintended operations.

Tool categories and common use cases:

Read-only tools:

• Read: Access file contents
• Grep: Search file contents with regex
• Glob: Find files matching patterns
• Appropriate for analysis and reporting skills

Read-write tools:

• Write: Create new files
• Edit: Modify existing files
• Appropriate for content generation skills

Execution tools:

• Bash: Execute shell commands
• Essential for running scripts, installing dependencies, executing builds

Research tools:

• WebFetch: Retrieve web page contents
• WebSearch: Search the web for information
• Appropriate for skills needing current documentation or examples

Example allowed-tools configurations:

# Analysis skill: read-only access
allowed-tools: [Read, Grep, Glob]

# Content generator: read and write, no execution
allowed-tools: [Read, Write, Edit, Grep, Glob]

# Complete workflow: full access
# (allowed-tools omitted or set to all tools)

When developing skills, follow the principle of least privilege: grant only the tools necessary for the skill's function. This reduces risk of unintended modifications and makes skill behavior more predictable.

Our recommendation is to ONLY allow Claude to make changes in code that is managed by git. This means that if Claude accidentally deletes some files you can just roll back the changes.

Here is our recommended permissions file stored in your ~/.claude/setting.local.json file

{
  "permissions": {
    "allow": [
      "Skill(*)",
      "Bash(:*::*)",
      "FileSystem(read:./**/*.*,write:./**/*.*)"
    ],
    "deny": [],
    "ask": []
  }
}

This allows you to use all skills and all shell commands and also give Claude Code permissions to read and write from the current directory down. However you should always remember to startup Claude in the project home of your cloned git repository.

!!! warning Avoid starting Claude in your $HOME directory with these rules. This will give Claude the ability to to change all of your files and if they are not in git, there is no ability to undo these changes!

Diagram: Skill Permission Matrix

Purpose: Show which tools different skill types typically require

| Skill Type | Read | Grep | Glob | Write | Edit | Bash | WebFetch |
|---|---|---|---|---|---|---|---|
| Quality Analyzer | ✓ | ✓ | ✓ | ✓ | | | |
| Content Generator | ✓ | ✓ | ✓ | ✓ | ✓ | | |
| MicroSim Creator | ✓ | ✓ | ✓ | ✓ | | | ✓ |
| Workflow Orchestrator | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Script Executor | ✓ | | | ✓ | | ✓ | |

Note: ✓ indicates typically required tool

MicroSim Generator Recommendations:

1. chartjs-generator (Score: 25/100) - This is actually a markdown table, not a chart - better implemented directly in markdown
2. microsim-p5 (Score: 60/100) - Could create interactive table with checkmarks but markdown tables work well for static permission matrices
3. mermaid-generator (Score: 15/100) - Not designed for table/matrix representations

Skill Workflow Instructions

The markdown body of a SKILL.md file contains detailed, step-by-step instructions that Claude Code executes autonomously. Well-designed workflow instructions exhibit several characteristics:

Explicit sequencing: Steps numbered clearly (Step 1, Step 2, etc.) with dependencies identified. Each step should be completable before proceeding to the next.

Conditional logic: Decision points where workflow branches based on file existence, quality metrics, or user input. Example: "If quality score < 70, prompt user to revise course description."

Verification checkpoints: Validation steps confirming expected files exist, contain required sections, and meet quality standards before proceeding.

Error handling guidance: Instructions for what to do when expected conditions aren't met. Example: "If learning-graph.csv not found, check for alternate filenames matching pattern learning-graph*.csv."

Output specifications: Detailed requirements for generated content including format, structure, naming conventions, and quality criteria.

Example workflow structure from the glossary-generator skill:

## Workflow

### Step 1: Verify Learning Graph Exists

Check for learning-graph.csv in /docs/learning-graph/ directory.

Actions:
- Use Glob tool to search for learning-graph*.csv
- If not found, inform user and request path to learning graph
- Read the CSV file to extract ConceptLabel column

### Step 2: Generate Definitions

For each concept label, generate an ISO 11179-compliant definition.

Requirements:
- Precise: Exact meaning without ambiguity
- Concise: Minimal words needed
- Distinct: Differentiated from related concepts
- Non-circular: Doesn't define concept using itself
- Factual: No business rules or implementation details

### Step 3: Create Glossary File

Write glossary.md in /docs/glossary/ directory.

Format:
- Alphabetically sorted terms
- Each term as level 2 heading (##)
- Definition in paragraph below
- Back-to-top links after each entry

This structure provides Claude Code with sufficient detail to execute the skill autonomously while maintaining flexibility for handling variations in project structure.

Installing a Claude Skill

Skills can be installed globally (available across all projects) or locally (available only in a specific project). The installation process creates the .claude/skills/ directory structure and copies skill files to the appropriate location.

Global Installation

Global installation makes skills available in all Claude Code sessions regardless of current working directory. Skills are stored in ~/.claude/skills/ in the user's home directory.

Installation process:

1. Create skills directory structure:

mkdir -p ~/.claude/skills/skill-name

2. Copy skill files:

cp skill-name/SKILL.md ~/.claude/skills/skill-name/
cp -r skill-name/references ~/.claude/skills/skill-name/  # if present

3. Verify installation:

ls -la ~/.claude/skills/

For this course's skills, the provided install-claude-skills.sh script automates global installation:

cd scripts
./install-claude-skills.sh

This script iterates through all skill directories in ./skills/, creating symlinks from ~/.claude/skills/ to the source files. Symlinks enable editing skills in the original repository while having them accessible globally—changes immediately propagate without reinstallation.

Project-Local Installation

Project-local installation confines skills to a specific project, appropriate for specialized workflows unique to that textbook or for testing skills before global deployment.

Installation process:

1. Create project skills directory:

mkdir -p .claude/skills/skill-name

2. Copy skill files to project:

cp /path/to/skill-name/SKILL.md .claude/skills/skill-name/

3. Verify in project context:

ls -la .claude/skills/

Project-local skills take precedence over global skills with the same name, enabling project-specific customization of standard workflows.

Diagram: Skill Installation Locations and Priority

Purpose: Show where skills can be installed and which location takes precedence

Components to show:
- User Home Directory level
  - ~/.claude/skills/ (global skills)
- Project Directory level
  - /project/.claude/skills/ (project-local skills)
- Skill Loading Priority indicator (project-local overrides global)
- Example: If both locations have "quiz-generator", project-local version used

Layout: Hierarchical tree structure

Labels:
- "~/.claude/skills/: Global skills available in all projects"
- ".claude/skills/: Project-specific skills or overrides"
- "Priority: Project > Global"

Visual style: Directory tree diagram with folder icons

Color scheme: Blue for global location, green for project-local, orange for priority indicator

Implementation: SVG diagram with tree structure

MicroSim Generator Recommendations:

1. mermaid-generator (Score: 85/100) - Perfect for hierarchical tree structures showing directory relationships and priority rules
2. microsim-p5 (Score: 70/100) - Could create custom directory tree with folder icons and priority indicators
3. vis-network (Score: 55/100) - Could show as network graph but hierarchical tree is more natural for directory structures

Listing Available Skills

Discovering which skills are installed and available is essential for workflow planning. Multiple methods exist for listing skills, each providing different levels of detail.

Using the /skills Slash Command

The /skills slash command provides the quickest way to list available skills from within a Claude Code session:

/skills

This command outputs a formatted list of all skills accessible from the current project, including both globally installed and project-local skills. Each entry shows the skill name and description from the SKILL.md frontmatter.

Using list-skills.sh Script

The scripts/list-skills.sh bash script provides more detailed skill listings with various output formats:

Basic listing:

./scripts/list-skills.sh

Outputs skill names and descriptions in human-readable format.

JSON format:

./scripts/list-skills-format.sh json

Produces JSON array of skill objects with name, description, and file path—useful for programmatic processing or integration with other tools.

Markdown format:

./scripts/list-skills-format.sh markdown

Generates markdown-formatted list suitable for documentation or README files.

The listing scripts search both ~/.claude/skills/ and the current project's .claude/skills/ directories, indicating which skills are globally versus locally installed.

Programmatic Skill Discovery

For integration with custom workflows or tooling, skills can be discovered programmatically by searching for SKILL.md files and parsing their YAML frontmatter:

find ~/.claude/skills -name "SKILL.md" -type f

This approach enables building custom skill managers, automated testing frameworks, or skill catalog generation for documentation sites.

Invoking Skills with Slash Commands

Skills are invoked using slash commands with the syntax /skill skill-name or through the Skill tool in direct tool use.

Basic Invocation

To execute a skill, type the slash command followed by the skill name (without file extension):

/skill learning-graph-generator

Claude Code loads the corresponding SKILL.md file, processes the frontmatter to configure permissions, and begins executing the workflow instructions sequentially.

Skill Execution Process

When a skill is invoked:

1. Skill loading: Claude Code locates SKILL.md in .claude/skills/ or ~/.claude/skills/
2. Permission configuration: allowed-tools frontmatter restricts available tools
3. Context inheritance: Skill receives full conversation history up to invocation point
4. Workflow execution: Claude Code processes markdown instructions as autonomous directives
5. Output generation: Skill produces specified files, reports, or artifacts
6. Completion report: Skill returns summary of actions taken and results achieved

Skills execute autonomously—once invoked, they make decisions about which files to read, what content to generate, and how to handle edge cases based on their workflow instructions. Users receive progress updates and final reports but don't need to make decisions at each step.

Passing Context to Skills

Skills have access to the conversation history before their invocation, enabling contextual understanding. Users can provide additional context by preceding the skill invocation with instructions:

Generate chapter content for junior-high reading level with emphasis on concrete examples

/skill chapter-content-generator

The skill receives both the general instruction and executes its standard workflow, incorporating the contextual guidance where applicable.

Diagram: Skill Invocation and Execution Lifecycle

Purpose: Illustrate what happens when a skill is invoked from command to completion

Visual style: Flowchart with swimlanes

Swimlanes:
- User
- Claude Code System
- Skill Executor
- File System

Steps:
1. Start (User): "User types /skill skill-name"
   Hover text: "Example: /skill glossary-generator"

2. Process (Claude Code): "Locate SKILL.md file"
   Hover text: "Search .claude/skills/ then ~/.claude/skills/ for matching skill"

3. Decision (Claude Code): "Skill found?"
   Hover text: "Check if SKILL.md exists in either location"

4a. End (User): "Error: Skill not found"
    Hover text: "Suggest running /skills to see available skills"

4b. Process (Claude Code): "Parse YAML frontmatter"
    Hover text: "Extract name, description, allowed-tools"

5. Process (Claude Code): "Configure tool permissions"
   Hover text: "Restrict to allowed-tools if specified"

6. Process (Skill Executor): "Load workflow instructions"
   Hover text: "Read markdown body from SKILL.md"

7. Process (Skill Executor): "Execute Step 1"
   Hover text: "Follow workflow instructions autonomously"

8. Process (File System): "Read/write files as directed"
   Hover text: "Access course description, learning graphs, generate content"

9. Decision (Skill Executor): "More steps?"
   Hover text: "Check if workflow complete"

10. Loop: Execute next step (back to step 7)
    Hover text: "Continue through all workflow steps"

11. Process (Skill Executor): "Generate completion report"
    Hover text: "Summarize actions taken, files created, quality metrics"

12. End (User): "Display results and next steps"
    Hover text: "User sees summary and can proceed with next task"

Color coding:
- Blue: User interactions
- Purple: System processing
- Green: Skill execution
- Orange: File operations

Implementation: SVG flowchart with decision diamonds and process rectangles

MicroSim Generator Recommendations:

1. mermaid-generator (Score: 95/100) - Ideal for flowchart with swimlanes, decision diamonds, process rectangles, and sequential steps
2. microsim-p5 (Score: 65/100) - Could build custom flowchart with interactivity but Mermaid provides standard flowchart patterns
3. vis-network (Score: 30/100) - Could show as network but lacks flowchart-specific shapes and swimlane organization

Skill Execution Context

Skills execute within a context that includes:

Conversation history: All messages and tool calls prior to skill invocation, enabling skills to understand project state and user objectives.

Working directory: The current directory where Claude Code was launched, typically the project root.

File system access: Ability to read and write files within project directory tree (subject to tool permissions).

Isolated state: Each skill invocation starts fresh—skills don't maintain state across invocations unless they write to files.

Understanding this context model helps in designing effective skills. For instance, the learning-graph-generator skill reads the course description file to understand course scope, generates concepts based on that description, and writes results to files that subsequent skills (like glossary-generator) will read.

Understanding Claude Commands

Claude Commands provide a simpler alternative to skills for single-purpose prompt expansions. While skills execute multi-step workflows autonomously, commands simply expand to a predefined prompt, effectively providing reusable prompt templates.

Commands are defined in markdown files in the .claude/commands/ directory. Unlike skills, commands don't have YAML frontmatter—they consist purely of the prompt text to be executed.

Command Definition Files

A command file contains only the prompt that should be executed when the command is invoked. For example, review-code.md might contain:

Review the code in this project for:
- Security vulnerabilities
- Performance issues
- Code style consistency
- Best practice violations

Provide a prioritized list of issues with specific file locations and suggested fixes.

When a user types /review-code, Claude Code replaces the command with this prompt and executes it in the current context.

Installing Claude Commands

Commands are installed similarly to skills but in the .claude/commands/ directory:

Global installation:

mkdir -p ~/.claude/commands/
cp command-name.md ~/.claude/commands/

Project-local installation:

mkdir -p .claude/commands/
cp command-name.md .claude/commands/

Like skills, project-local commands take precedence over global commands with the same name.

Difference Between Skills & Commands

The fundamental distinction between skills and commands lies in autonomy and complexity:

When to use skills:

• Multi-step workflows requiring sequential operations
• Tasks needing file reading, analysis, and generation
• Processes with quality validation checkpoints
• Operations requiring consistency across projects

When to use commands:

• Simple prompt templates used frequently
• Single-request operations
• Project-specific prompt patterns
• Quick shortcuts for common questions

In this course, the intelligent textbook workflow relies primarily on skills due to the complexity and multi-step nature of content generation. Commands might be used for auxiliary tasks like "check-concept-coverage" or "validate-markdown-format."

Diagram: Skills vs Commands Decision Tree

Purpose: Help users decide whether to create a skill or command for their use case

Visual style: Decision tree with yes/no branches

Decision points:
1. Start: "Do you need to perform multiple sequential steps?"
   Yes → Continue to 2
   No → "Consider using a Command"

2. "Do you need to read from and write to multiple files?"
   Yes → Continue to 3
   No → "Consider using a Command"

3. "Do you need quality validation or error handling?"
   Yes → Continue to 4
   No → "Simple Skill might work"

4. "Will this workflow be reused across multiple projects?"
   Yes → "Create a Skill with full workflow"
   No → "Project-local Skill or Command"

Terminal nodes:
- "Create a Skill": For complex, reusable workflows
- "Use a Command": For simple prompt templates
- "Simple Skill might work": For straightforward multi-step tasks
- "Project-local Skill or Command": For project-specific automation

Color coding:
- Green: Indicates skill is appropriate
- Yellow: Indicates command might suffice
- Orange: Indicates borderline case

Implementation: SVG decision tree with diamond decision nodes

MicroSim Generator Recommendations:

1. mermaid-generator (Score: 92/100) - Perfect for decision tree with yes/no branches, diamond decision nodes, and terminal outcomes
2. microsim-p5 (Score: 70/100) - Could create custom interactive decision tree with color-coded paths
3. vis-network (Score: 40/100) - Could show as network but decision trees need specific branching layout

Token Management Strategies

Effective use of Claude requires understanding and managing token consumption. Claude Pro accounts provide generous but finite token budgets within 4-hour usage windows, making token management essential for sustained productivity on textbook projects.

Understanding Tokens

Tokens represent the fundamental units of text processing in large language models. A token typically corresponds to:

• One word (e.g., "textbook" = 1 token)
• Part of a long word (e.g., "educational" might be 2-3 tokens)
• Punctuation marks (e.g., "." = 1 token)
• Whitespace (spaces generally included with adjacent words)

On average, English text contains approximately 1 token per 4 characters or 1 token per 0.75 words. Technical content with specialized terminology may consume more tokens due to uncommon word fragments.

Both input (prompts, file contents, conversation history) and output (generated text) count toward token consumption. For intelligent textbook workflows, large inputs (entire learning graphs, multiple chapter files) combined with extensive outputs (comprehensive chapter content) can accumulate tokens quickly.

Claude Token Limits

Claude Code uses the Sonnet or Opus models depending on task complexity. As of 2025, typical token windows are:

• Context window: 200,000 tokens (amount of text Claude can consider simultaneously)
• Output limit: ~4,000-8,000 tokens per response (model-dependent)

These generous limits enable Claude to process entire textbook chapters, comprehensive learning graphs, and extensive reference materials in a single context. However, the cumulative token consumption across an entire session must be managed within Claude Pro usage limits.

4-Hour Usage Windows

Claude Pro accounts operate on a rolling 4-hour usage window model. Rather than a daily reset, your available capacity regenerates continuously based on when tokens were consumed.

How it works:

1. You have a token budget (specific amount varies by subscription tier)
2. Each request consumes tokens from this budget
3. After 4 hours, those tokens return to your available pool
4. Usage resets continuously, not at a fixed daily time

Example: If you consume 50,000 tokens at 9:00 AM, those tokens remain unavailable until 1:00 PM (4 hours later), when they're restored to your budget.

This model rewards distributed work patterns over concentrated bursts. For textbook creation workflows that may involve generating content for 13 chapters, spreading skill invocations across several sessions prevents exhausting your token budget.

Diagram: 4-Hour Token Window Visualization

Purpose: Show how token usage and regeneration works over time

Time period: 12-hour window

Orientation: Horizontal timeline with token budget shown as vertical bar chart below

Events:
- 9:00 AM: Generate Chapter 1 content (consume 30,000 tokens)
- 9:30 AM: Generate glossary (consume 15,000 tokens)
- 11:00 AM: Generate Chapter 2 content (consume 30,000 tokens)
- 1:00 PM: 9:00 AM tokens restored (+30,000 tokens)
- 1:30 PM: 9:30 AM tokens restored (+15,000 tokens)
- 3:00 PM: 11:00 AM tokens restored (+30,000 tokens)
- 5:00 PM: Available budget fully replenished

Visual elements:
- Timeline showing activity times
- Stacked bar chart below showing available vs consumed tokens at each time point
- Rolling 4-hour window indicator
- Annotations showing "Tokens consumed" and "Tokens restored"

Color coding:
- Blue: Available token budget
- Orange: Consumed tokens
- Green: Restored tokens
- Gray: 4-hour restoration window

Interactive features:
- Hover over timeline events to see token amounts
- Hover over bars to see total available vs used

Implementation: HTML/CSS/JavaScript with Chart.js timeline

MicroSim Generator Recommendations:

1. timeline-generator (Score: 92/100) - Excellent for temporal events with specific times showing token consumption/restoration over 12-hour period
2. chartjs-generator (Score: 85/100) - Good for stacked bar chart showing available vs consumed tokens over time, Chart.js explicitly mentioned
3. microsim-p5 (Score: 65/100) - Could create custom timeline with animated token restoration

Optimizing Claude Usage

Several strategies maximize productivity within token budgets:

Strategy 1: Batch related operations

Rather than generating one chapter at a time with full context reloading, batch similar operations together. Generate all quiz questions in one session, all MicroSim specifications in another.

Strategy 2: Use focused contexts

When invoking skills, provide only necessary context. Don't include the entire learning graph if the skill only needs concept labels. Use skill-specific context loading rather than maintaining everything in conversation history.

Strategy 3: Leverage file-based state

Skills that write intermediate results to files enable breaking workflows into smaller sessions. Generate chapter outlines in one session, detailed content in another—the outline file provides continuity without maintaining conversation history.

Strategy 4: Progressive refinement over regeneration

When chapter content needs adjustment, use targeted edits rather than regenerating entire chapters. Edit specific sections or add missing concepts rather than rewriting from scratch.

Strategy 5: Monitor usage patterns

Track which skills consume the most tokens (typically learning-graph-generator and chapter-content-generator for large textbooks). Plan sessions to stay within 4-hour windows for these heavy operations.

Strategy 6: Use appropriate model variants

For simpler tasks like validating markdown formatting or checking concept coverage, request that Claude use more efficient models. Reserve Opus for complex reasoning and content generation.

Iterative Prompt Refinement

Effective prompt engineering for skills and educational content generation follows an iterative refinement cycle: draft, test, evaluate, refine, repeat. This section explores techniques for systematically improving prompts to achieve desired educational outcomes.

Initial Prompt Drafting

The first iteration focuses on establishing basic structure and requirements:

1. Define learning objectives: What should learners understand or be able to do?
2. Specify output format: Markdown sections, details blocks, specific structures
3. Identify constraints: Reading level, word count, concept coverage
4. Provide examples: Reference materials demonstrating desired quality

For a chapter content generation prompt, an initial draft might specify:

• Target reading level (graduate)
• Concepts to cover (list from chapter outline)
• Required sections (introduction, concept explanations, summary)
• Interactive element frequency (every 3-5 paragraphs)

Testing and Evaluation

Execute the prompt and evaluate outputs against quality criteria:

Content coverage: Are all required concepts addressed with adequate depth?

Reading level appropriateness: Does sentence complexity, vocabulary, and explanation style match target level?

**Structural

…(truncated)