Academic workflows for teaching - Course material generation: exams, quizzes, slides, lectures, assignments, rubrics, and Canvas LMS export.
⚠️ Scholar is now teaching-only (v3.0.0). The research surface — literature, manuscript, simulation, and research-planning commands plus all skills — was removed in v3.0.0, with no replacement. Migrating from scholar v2.x? See what was removed.
A Claude Code plugin for academic teaching workflows. Features a unified Plugin + MCP architecture with 18 teaching commands (+ hub).
Teaching (18 commands)
/teaching:quiz <topic>- Generate quiz questions with answer keys ✅/teaching:exam <type>- Create comprehensive exams with rubrics. NEW in v2.18.0:--format exam-rich-latexfor evidence-based statistics exams ✅/teaching:assignment <topic>- Create homework assignments with solutions ✅/teaching:solution <file>- Generate standalone solution keys from assignment files ✅/teaching:syllabus <course>- Generate comprehensive course syllabus ✅/teaching:slides <topic>- Create lecture slides with examples ✅/teaching:rubric <type>- Generate detailed grading rubrics ✅/teaching:feedback <assignment>- Generate constructive student feedback ✅/teaching:demo [path]- Create demo course environment with sample materials ✅/teaching:lecture <topic>- Generate comprehensive lecture notes ✅/teaching:validate <file>- Validate YAML configuration files (multi-level) ✅/teaching:validate-r <file>- Validate R code chunks in.qmdfiles ✅/teaching:diff <file>- Compare YAML and JSON sync status ✅/teaching:sync [options]- Synchronize YAML to JSON ✅/teaching:migrate- Batch migrate YAML configs from v1 to v2 schema ✅/teaching:config <subcommand>- Manage prompts, config, and provenance ✅/teaching:preflight- Pre-release health checks for Scholar projects ✅/teaching:canvas <file>- Convert exam files to Canvas QTI format ✅
Command Discovery (1 command)
/scholar:hub [argument]- Browse all commands, drill into categories, get usage details ✅
Scholar is teaching-only and ships 1 skill — statistical-pedagogy-framework (added in
v3.1.0). The former research skills (mathematical, implementation, writing, discovery categories)
were removed in v3.0.0 — see what was removed.
Unified Plugin + MCP Pattern:
src/core/- Framework-agnostic business logicsrc/plugin-api/- Claude Plugin commandssrc/mcp-server/- MCP Protocol toolslib/- Shell API wrappers
This architecture eliminates IPC overhead by sharing core logic directly between both APIs.
Phase 0 Foundation + Teaching Commands:
src/teaching/templates/- Template system (exam, quiz, assignment, syllabus, lecture)src/teaching/generators/- AI-powered content generationsrc/teaching/config/- Configuration managementsrc/teaching/validators/- Multi-layer validation (Schema + LaTeX + Completeness)src/teaching/ai/- AI content generation with retry logictests/teaching/- 3,412 unit tests (100% passing)
See Phase 0 Architecture for detailed documentation.
Scholar is a pure plugin with no MCP server dependencies. It works immediately after installation in both Claude Code CLI and Claude Desktop app.
# Add the Data-Wise tap
brew tap data-wise/tap
# Install scholar plugin
brew install scholar
# Or upgrade existing installation
brew upgrade scholarThe Homebrew formula automatically:
- Installs the plugin to
~/.claude/plugins/scholar - Syncs Claude Code's plugin cache (new features available immediately)
- Makes it available in Claude Code CLI and Claude Desktop
- No additional configuration needed
Latest version: v3.1.1 (released 2026-06-21)
- 19 commands (18 teaching + 1 hub), 1 skill (teaching-only)
- 3,412 tests with 100% pass rate
- Comprehensive documentation (95% coverage)
For Claude Code CLI and Claude Desktop:
# Clone the repository
git clone https://github.com/Data-Wise/scholar.git
cd scholar
# Install in development mode (symlink - changes reflected immediately)
./scripts/install.sh --dev
# Or install in production mode (copy - stable)
./scripts/install.shInstallation locations:
- Plugin directory:
~/.claude/plugins/scholar - Commands:
~/.claude/plugins/scholar/src/plugin-api/commands/ - Shell APIs:
~/.claude/plugins/scholar/lib/
# When published to npm (future release):
npm install -g @data-wise/scholar
scholar-install # Installs plugin to ~/.claude/plugins/# Check plugin directory exists
ls -la ~/.claude/plugins/scholar
# Verify plugin.json
cat ~/.claude/plugins/scholar/.claude-plugin/plugin.json
# Run test suite (if installed from source)
cd ~/projects/dev-tools/scholar
./tests/test-plugin-structure.shExpected output:
✅ All tests passed (10/10)
- Plugin structure valid
- 19 commands present (18 teaching + 1 hub)
- 1 skill (teaching-only: statistical-pedagogy-framework)
- No hardcoded paths
- v3.1.1 verified
After installation, commands are immediately available:
# Start Claude Code in any directory
claude
# Use scholar commands
/teaching:syllabus "Statistics 101"
/teaching:exam "midterm"
/scholar:hubScholar automatically loads when you open Claude Desktop. Commands work the same way:
- Open Claude Desktop app
- Start a new conversation
- Use slash commands:
/teaching:syllabus,/teaching:exam,/scholar:hub, etc.
Scholar does NOT require any MCP server configuration.
Unlike plugins like rforge that depend on MCP servers, Scholar uses shell-based API wrappers (lib/arxiv-api.sh, lib/crossref-api.sh, lib/bibtex-utils.sh) for external services.
Benefits of pure plugin approach:
- ✅ Faster startup (no IPC overhead)
- ✅ Simpler installation (no server configuration)
- ✅ More portable (works anywhere Claude Code/Desktop runs)
- ✅ Self-contained (all dependencies included)
Future MCP integration (Phase 2): In a future release, Scholar may optionally integrate with an MCP server for advanced features like:
- R execution for statistical analysis
- Zotero library integration
- LaTeX compilation
This will be optional - all current commands will continue to work without MCP.
This is planned for a future release.
# Create course syllabus
/teaching:syllabus "Introduction to Statistics"
# Generate homework assignment
/teaching:assignment "Linear Regression"
# Create grading rubric
/teaching:rubric "data analysis project"Looking for research commands (literature, manuscript, simulation, research planning)? They were removed in v3.0.0, with no replacement — see what was removed.
All teaching commands support the --config flag to explicitly specify a configuration file path:
/teaching:quiz "Linear Regression" --config /path/to/config.yml
/teaching:exam midterm --config .flow/teach-config.ymlWhen to use --config:
- Integration with automation tools (e.g., flow-cli)
- Using non-standard config locations
- Testing with different configurations
- CI/CD pipelines
Behavior:
- With
--config: Loads the specified YAML file directly (skips parent directory search) - Without
--config: Searches parent directories for.flow/teach-config.yml(default) - Validation: Lenient mode (warnings only) to avoid blocking workflow automation
- Debug: Use
[scholar:config]prefix in logs to track config source
Example workflow integration:
# flow-cli passes explicit config path
claude --print "/teaching:exam Midterm --config $(pwd)/.flow/teach-config.yml"Generate quiz questions with answer keys.
Examples:
/teaching:quiz "Linear Regression"
/teaching:quiz "Hypothesis Testing" --questions 10 --type practiceOptions:
--questions N- Number of questions (default: 5)--type TYPE- Quiz type: reading, practice, checkpoint, pop, review--duration N- Duration in minutes (default: 15)--difficulty LEVEL- beginner, intermediate, advanced
Output Formats: markdown, json, canvas (QTI)
Create comprehensive exams with rubrics.
Examples:
/teaching:exam midterm --questions 20 --duration 90
/teaching:exam final --topics "regression,ANOVA,hypothesis testing"
/teaching:exam stat-545-final --format exam-rich-latex --topics "two-way ANOVA"Options:
--type TYPE- midterm, final, practice, comprehensive--questions N- Number of questions--duration N- Duration in minutes--topics "t1,t2"- Specific topics to cover--format FORMAT- md (default), tex, qmd, canvas, json, exam-rich-latex (v2.18.0)
Output: JSON with questions, answer key, grading rubric. exam-rich-latex emits a Quarto .qmd using the LaTeX exam class with an evidence-based reporting policy, F-critical bracket table, and
Create homework assignments and problem sets.
Examples:
/teaching:assignment "Linear Regression"
/teaching:assignment homework --problems 5 --difficulty intermediate
/teaching:assignment lab --topic "Bootstrap Methods" --include-codeOptions:
--type TYPE- homework, problem-set, lab, project, worksheet--problems N- Number of problems (default: 5)--points N- Total points (default: 100)--include-code- Include programming problems--language R|Python- Programming language
Output: JSON with problems, solutions, grading rubric
Generate a comprehensive course syllabus.
Examples:
/teaching:syllabus "Introduction to Statistics"
/teaching:syllabus "Regression Analysis" "Fall 2026"Options:
--weeks N- Number of weeks (default: 16)--level LEVEL- undergraduate, graduate, doctoral--format FORMAT- in-person, online, hybrid
Output Formats: markdown, json, latex, html
Includes:
- Course and instructor information
- Learning objectives (measurable, action verbs)
- Grading policy with scale
- Week-by-week schedule
- Standard policies (academic integrity, accessibility, etc.)
Create lecture slides with examples.
Examples:
/teaching:slides "Multiple Regression"
/teaching:slides "Hypothesis Testing" 75
/teaching:slides "ANOVA" --format revealOptions:
--duration N- Duration in minutes (default: 50)--format FORMAT- markdown, reveal, beamer, quarto--include-code- Include code examples--subtopics "t1,t2"- Specific subtopics
Slide Count by Duration:
- 50 min → ~20 slides
- 75 min → ~30 slides
- 90 min → ~36 slides
Output: Slides with speaker notes, organized by type (title, objectives, content, example, practice, summary)
Generate detailed grading rubrics.
Examples:
/teaching:rubric "data analysis project"
/teaching:rubric "research paper" 100Includes:
- Clear criteria for each performance level
- Point allocations
- Observable, measurable descriptors
Validate YAML configuration files against schema.
Examples:
/teaching:validate .flow/teach-config.yml
/teaching:validate content/lesson-plans/week03.yml
/teaching:validate --all # Validate all YAML files in projectOptions:
--all- Validate all YAML configs in project--strict- Strict validation mode (errors on warnings)--quiet- Suppress warnings, errors only
Validation Levels:
- YAML Syntax - Valid YAML structure (indentation, colons, quotes)
- JSON Schema - Conforms to teach-config or lesson-plan schema
-
LaTeX Validation - Math notation compiles (
$...$,$$...$$) - Completeness - Required fields present (course_info, defaults, style)
Output Format:
IDE-style error messages:
file:line:col: error message
file:line:col: warning message
Summary:
✅ Validation passed (0 errors, 2 warnings)
❌ Validation failed (3 errors, 1 warning)
Use Cases:
- Pre-commit validation (ensure configs are valid before commit)
- CI/CD pipelines (block deploys with invalid configs)
- Development debugging (find syntax errors quickly)
- Migration testing (validate after schema upgrades)
Exit Codes:
0- Validation passed1- Validation failed (errors found)2- File not found or YAML parse error
Compare YAML and JSON sync status.
Examples:
/teaching:diff teach-config.yml
/teaching:diff content/lesson-plans/week03.yml
/teaching:diff --all # Check sync status for all configsOptions:
--all- Check sync status for all YAML/JSON pairs--verbose- Show detailed diff output--json- Output sync status as JSON
Output:
{
"file": "teach-config.yml",
"inSync": true,
"yamlHash": "a3b2c1d4...",
"jsonHash": "a3b2c1d4...",
"lastSync": "2026-01-15T10:30:00Z",
"cacheAge": "5m 30s"
}Sync States:
- ✅ In Sync - YAML and JSON match (identical hashes)
⚠️ Out of Sync - YAML changed, JSON needs update- ❌ Missing JSON - JSON file doesn't exist (run
/teaching:sync) - ❌ Invalid YAML - YAML has syntax/schema errors
Use Cases:
- Verify sync before command execution
- Debug sync issues (stale cache, missing JSON)
- CI/CD validation (ensure configs are synced)
- Pre-deployment checks
Performance:
- Hash comparison: ~5ms per file
- Cache lookup: ~2ms per file
- No file parsing (hash-based only)
Synchronize YAML to JSON (manual trigger).
Examples:
/teaching:sync # Sync all YAML files in project
/teaching:sync teach-config.yml # Sync specific file
/teaching:sync --force # Force re-sync (ignore cache)Options:
--force- Force re-sync (bypass hash check, rewrite all JSON)--dry-run- Preview sync without writing files--verbose- Show detailed sync progress
Sync Process:
- Find YAML - Locate all
*.ymlfiles in.flow/andcontent/ - Hash Check - Compare SHA-256 hash with cache (skip if unchanged)
- Validate - 4-level validation (YAML, schema, LaTeX, completeness)
- Parse - Parse YAML to JSON
- Write - Write JSON to same directory as YAML
- Cache - Update
.scholar-cache/sync-status.jsonwith new hash
Performance:
- Unchanged files: ~5ms (hash check only)
- Changed files: ~80ms (parse + validate + write)
- Typical project (10 files): ~150ms total
Output:
Syncing 10 YAML files...
✅ teach-config.yml → teach-config.json (80ms)
⏭️ week01.yml (unchanged, skipped)
⏭️ week02.yml (unchanged, skipped)
✅ week03.yml → week03.json (75ms)
❌ week04.yml (validation failed, see errors below)
Summary:
2 synced, 2 skipped, 1 failed
Total time: 155ms
Automatic Sync Triggers:
- Pre-command hook (before Scholar commands run)
- Pre-commit hook (before git commits)
- GitHub Actions (on CI/CD push)
Manual Sync When:
- Testing config changes before committing
- Debugging sync issues (stale cache, corrupt JSON)
- Forcing full re-sync after cache corruption
Cache Location:
.scholar-cache/
sync-status.json # Hash tracking, sync timestamps
Error Handling:
- Validation errors block sync (prevents broken JSON)
- Missing YAML files are skipped (warnings only)
- Corrupt cache is auto-rebuilt on next sync
Migrate YAML configuration files from v1 to v2 schema with atomic batch migration.
Examples:
/teaching:migrate --detect # Find v1 files with complexity
/teaching:migrate --dry-run # Preview migration changes
/teaching:migrate # Apply migration with git commit
/teaching:migrate --file week-01.yml # Migrate single file
/teaching:migrate --no-git # Apply without git commitModes:
--detect- Find v1 schema files and show complexity scoring (0-10)--dry-run- Preview colored diffs without modifying files- Default mode - Apply migration with git commit automation
--file <path>- Migrate specific file only
Options:
--no-git- Skip git commit (still applies migration)--no-git-check- Skip git safety check (dangerous - may lose uncommitted work)--patterns <glob>- Custom glob patterns (comma-separated)--debug- Enable debug logging
Features:
- Atomic semantics - All-or-nothing migration with rollback
- Git integration - Automated commits with descriptive messages
- Git safety - Checks for uncommitted changes before migration
- Complexity scoring - Helps prioritize migration effort
- Security hardened - Uses
execFileNoThrow(prevents command injection)
Complexity Categories:
- Simple (0-3): Few field renames
- Medium (4-6): Multiple renames + type conversions
- Complex (7-10): Many changes + nested structures
Rollback Guarantee:
- In-memory backups of all files
- Automatic rollback on any failure
- Restores exact original content
Output:
Found 12 v1 schema files
Step 1: Detecting v1 schema files...
Step 2: Checking git status...
Step 3: Migrating files...
[1/12] week-01.yml... ✅
[2/12] week-02.yml... ✅
...
✓ Migration complete!
Processed: 12 files
Commit: abc123
Next steps:
1. Review changes: git show abc123
2. Validate configs: /teaching:validate
3. Push to remote: git push
Scholar is teaching-only and ships 1 skill — statistical-pedagogy-framework (added in
v3.1.0). The former research skills (4-category set: mathematical, implementation, writing,
discovery) were removed in v3.0.0 — see what was removed.
scholar/
├── src/
│ ├── teaching/ # Course material generation (teaching-only)
│ │ ├── ai/ # AI provider with retry logic
│ │ ├── config/ # Configuration loader
│ │ ├── templates/ # Template system
│ │ └── validators/ # Validation engine
│ ├── plugin-api/ # Claude Plugin commands
│ │ ├── commands/
│ │ │ ├── hub.md # Command discovery hub
│ │ │ └── teaching/ # 18 teaching commands
│ │ └── skills/ # 1 skill (statistical-pedagogy-framework)
│ ├── discovery/ # Discovery + smart-help engine
│ └── mcp-server/ # MCP Protocol tools
├── lib/ # Shell API wrappers
├── tests/ # Test suite
│ └── teaching/ # Teaching command tests
└── scripts/ # Installation scripts
Benefits:
- No IPC overhead (shared core library)
- Single source of truth for business logic
- Both APIs consume the same tested code
- Easy to maintain and extend
- Teaching foundation ready for command implementation
Phase 0 Components (Complete):
- Template System - Base schemas with inheritance and auto-field injection
- Config Loader - Parent directory search for
.flow/teach-config.yml - Validator Engine - Multi-layer validation (JSON Schema + LaTeX + Completeness)
- AI Provider - Content generation with retry logic and rate limiting
See Phase 0 Architecture Documentation for details.
Scholar v2.2.0 introduces a dual-config system where you write YAML configs (human-friendly) and Scholar automatically maintains JSON files (machine-optimized) with sub-100ms sync latency.
┌─────────────────┐ ┌──────────────────┐
│ YAML (source) │ ────→ │ JSON (auto) │
│ You edit this │ sync │ Never edit this │
└─────────────────┘ └──────────────────┘
teach-config.yml teach-config.json
Key Principles:
- YAML = Source of Truth - Edit only YAML files
- JSON = Generated - Auto-synced from YAML (gitignored)
- Fast Sync - Hash-based change detection (< 100ms)
- Safe - Validation errors prevent broken configs
Sync happens automatically in these scenarios:
- Before Command Execution - Pre-command hook ensures configs are synced
- Pre-Commit Hook - Git hook validates and syncs before commits
- CI/CD Pipeline - GitHub Actions workflow validates schemas
# Sync YAML to JSON
/teaching:sync
# Check sync status
/teaching:diff teach-config.yml
# Validate YAML schema
/teaching:validate teach-config.ymlScholar uses SHA-256 hashing to skip unchanged files:
.scholar-cache/
sync-status.json # Tracks file hashes and sync timestamps
Performance:
- Changed files: Parse + Validate + Write JSON (~80ms)
- Unchanged files: Hash check only (~5ms)
- Cache invalidation: Automatic on YAML modification
course-repo/
├── .flow/
│ ├── teach-config.yml # YAML config (source)
│ └── teach-config.json # JSON config (auto-generated)
├── .scholar-cache/
│ └── sync-status.json # Hash tracking
├── content/
│ └── lesson-plans/
│ ├── week01.yml # YAML lesson plan (source)
│ └── week01.json # JSON lesson plan (auto-generated)
└── .gitignore # Excludes *.json and .scholar-cache/
Scholar performs 4-level validation during sync:
- YAML Syntax - Valid YAML structure
- JSON Schema - Conforms to teach-config schema
- LaTeX Validation - Math notation compiles
- Completeness - Required fields present
Error Handling:
- Validation errors block sync (prevents broken configs)
- IDE-style error output:
file:line:col: message - Lenient mode with
--configflag (warnings only)
Automate validation in CI/CD:
# .github/workflows/validate.yml
- name: Validate Configs
run: |
npm install -g @data-wise/scholar
scholar validate .flow/teach-config.ymlSee docs/github-actions-setup.md for complete workflow examples.
Before v2.2.0:
# Edit YAML, manually convert to JSON
vim .flow/teach-config.yml
# (manual conversion required)With v2.2.0:
# Edit YAML, sync happens automatically
vim .flow/teach-config.yml
git add .flow/teach-config.yml # Sync in pre-commit hookSee MIGRATION-v2.2.0.md for detailed upgrade guide.
cd scholar
./tests/test-plugin-structure.shTest Coverage:
- ✅ Required files present
- ✅ Valid JSON in plugin.json
- ✅ Directory structure
- ✅ 19 commands exist (18 teaching + 1 hub)
- ✅ Teaching commands present
- ✅ 1 skill (teaching-only: statistical-pedagogy-framework)
- ✅ API wrappers present
- ✅ No hardcoded paths
- ✅ Valid command frontmatter
Commands are in src/plugin-api/commands/. Each command is a markdown file with:
- YAML frontmatter (name, description)
- User-facing documentation
<system>block with implementation details
Example:
---
name: exam
description: Generate comprehensive exams from course material
---
# Generate Exam
User-facing instructions here...
<system>
Implementation details for Claude...
</system>- Create
.mdfile in appropriate category directory - Add frontmatter with
name:anddescription: - Write user-facing documentation
- Add
<system>block with implementation - Test:
/namespace:command "test input"
Teaching Infrastructure Layer
- ✅ Template system with inheritance and auto-fields
- ✅ Configuration loader with parent directory search
- ✅ Multi-layer validation (JSON Schema + LaTeX + Completeness)
- ✅ AI provider with retry logic and rate limiting
Components:
src/teaching/templates/- Template systemsrc/teaching/config/- Configuration managementsrc/teaching/validators/- Validation enginesrc/teaching/ai/- AI content generation
Documentation:
- ✅ 3 teaching commands (syllabus, assignment, rubric)
- ✅ Shell API wrappers
- ✅ Unified directory structure
- ✅ Installation scripts
- ✅ Test suite
Phase 1 also shipped a research command + skill set; those were removed in v3.0.0 (scholar is now teaching-only). See what was removed.
Core Teaching Commands - 2,252 tests, 100% passing
-
✅
/teaching:quiz(33 tests)- Multiple question types (MC, true-false, short-answer, numerical)
- Quiz types: reading, practice, checkpoint, pop, review
- Canvas QTI export support
- Conversational generation for Claude Max users
-
✅
/teaching:exam(existing)- Question bank generation
- Answer key creation
- LaTeX math support
-
✅
/teaching:assignment(41 tests)- Problem types: homework, problem-set, lab, project, worksheet
- Multi-part problems with solutions
- Grading rubrics with partial credit
- Code problems support (R, Python)
-
✅
/teaching:syllabus(48 tests)- Course information and instructor details
- Learning objectives (measurable, action verbs)
- Grading policy with scale
- Week-by-week schedule
- Standard policies (academic integrity, accessibility)
- Export: markdown, JSON, LaTeX, HTML
-
✅
/teaching:slides(50 tests)- Slide types: title, objectives, content, example, practice, summary
- Duration-based slide count calculation
- Speaker notes support
- Export: markdown, reveal.js, beamer, quarto
Pending Commands:
-
/teaching:feedback- Constructive student feedback -
/teaching:rubric- Enhanced with AI generation
- Implement MCP protocol tools in
src/mcp-server/ - Add TypeScript/Zod schemas
- Test MCP server independently
- Integrate with Claude Desktop app
- LMS integration (Canvas, Blackboard)
- Export to PDF/Word formats
- Calendar integration
- Student roster management
- Real-time collaboration
Contributions are welcome! This is a standalone project focused on academic workflows.
Development workflow:
- Fork the repository: https://github.com/Data-Wise/scholar
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes
- Run tests:
./tests/test-plugin-structure.sh - Commit with clear messages
- Push and submit a pull request
See also:
- claude-plugins monorepo for shared tooling and standards
- craft and rforge - Related projects
MIT License - see LICENSE file for details.
- Issues: https://github.com/Data-Wise/scholar/issues
- Repository: https://github.com/Data-Wise/scholar
- Documentation: See
docs/directory for comprehensive guides
- craft - Full-stack developer toolkit (86 commands, 8 agents, 21 skills)
- rforge - R package ecosystem orchestrator with mode system
- claude-plugins - Shared tooling and plugin development standards
Migration from older plugins:
workflow→ Merged into craft (v1.17.0)statistical-research→ Superseded by scholar (v1.0.0)
Ready to use! Try: /scholar:hub or /teaching:exam "your course topic"