LabSmith

LabSmith generates hands-on technical workshop lab guides. You describe the workshop you need — what vendor gear, what topics, what skill level — and LabSmith plans the modules, writes the content, and compiles a ready-to-deliver guide with all the CLI commands, verification steps, and instructor notes included.

It was built for Fortinet workshops first (FortiGate, FortiSwitch, FortiAP), but the design is vendor-agnostic. Modules are templates with {{PLACEHOLDER}} syntax for hardware-specific values. The compiler fills those in at build time from hardware profiles, so the same module works across different lab environments.

Requirements

• macOS 12+ or Linux
• Python 3.10+
• PyYAML (pip install pyyaml)
• For the CLI workshop planner: pip install anthropic and set ANTHROPIC_API_KEY
• For Cowork mode (recommended): Claude Desktop with Cowork — no API key needed

Two ways to use LabSmith

Option A: Cowork mode (no API key needed)

This is the primary workflow. Open the labsmith folder in Claude Desktop's Cowork mode and use plain English:

1. Plan a workshop — describe what you need ("I need a 2-day Cisco-to-Fortinet migration workshop for my lab with a FortiGate 120G, two FortiSwitch 224E-POE, and a FortiAP 431G"). The plan-workshop skill handles intake, proposes modules, validates that hardware profiles and reference docs exist, generates a config, and creates answer files for each module.

2. Generate modules — say "generate a module" or use /generate-module. Claude reads the answer file and reference material, then writes a complete module with CLI commands, verification steps, instructor notes, and placeholder-based hardware references.

3. Compile — the compiler resolves all {{PLACEHOLDER}} values from hardware profiles and the workshop config, numbers modules by position, and writes the final output.

4. QA — the QA script checks each module for completeness (header metadata, placeholder counts, instructor notes, CLI blocks, verification steps, and more).

Option B: Command line

# Plan a workshop (interactive)
python3 scripts/plan-workshop.py

# Plan from a file
python3 scripts/plan-workshop.py --input description.txt

# Generate a module from its answer file
python3 scripts/generate-module.py --answers-json planned/<slug>.json

# Compile a workshop
python3 compiler/compile.py configs/my-workshop.yaml

# QA a single module
bash scripts/qa-module.sh output/<workshop-dir>/module-00-prelab.md

# QA all modules in a workshop
for f in output/<workshop-dir>/module-*.md; do bash scripts/qa-module.sh "$f"; done

How it fits together

LabSmith has three main stages. Each one produces files that feed the next:

Planning takes a natural-language description and produces a workshop config YAML (in configs/) and per-module answer JSON files (in planned/). The config defines the workshop metadata, module order, and hardware assignments. The answer files capture the specific details each module needs.

Generation takes an answer file, reads the relevant hardware profiles (from profiles/) and vendor reference docs (from references/), and writes a complete module template to modules/. Modules use {{PLACEHOLDER}} syntax so they stay hardware-agnostic.

Compilation takes a workshop config, resolves all placeholders from profiles, numbers modules by their position in the workshop, and writes the final deliverable to output/.

Project layout

labsmith/
├── scripts/
│   ├── plan-workshop.py          # Workshop planner (NL input → config + answer files)
│   ├── generate-module.py        # Module generator (answer file → module template)
│   ├── qa-module.sh              # QA validator (10 automated checks per module)
│   ├── run-tests.sh              # Automated test suite
│   ├── extract-profile.sh        # Extract hardware profile from reference docs
│   ├── extract-references.py     # Extract reference material for module generation
│   └── clean-and-split.py        # Split combined reference docs into per-topic files
├── compiler/
│   └── compile.py                # Workshop compiler (resolves placeholders, numbers modules)
├── configs/                      # Workshop config YAMLs
├── modules/                      # Module templates organized by track/OS version
│   ├── cisco-to-fortinet/fortios-7.6/   # 10 modules
│   └── fortinet-homelab/fortios-7.6/    # 4 modules
├── profiles/                     # Hardware profiles (YAML) — 8 devices
├── planned/                      # Answer files from workshop planning (gitignored)
├── references/                   # Vendor docs — local only (gitignored)
├── output/                       # Compiled workshops — local only (gitignored)
├── marker/                       # PDF-to-markdown pipeline for ingesting vendor datasheets
├── skills/                       # Cowork skill definitions (generate-module, plan-workshop, close)
├── docs/
│   ├── labsmith-prd.md           # Product requirements document
│   ├── workshop-schema.md        # Workshop config YAML schema reference
│   └── placeholder-spec.md       # Placeholder naming conventions and rules
├── ARCHITECTURE.md               # System architecture and component details
├── CHANGELOG.md                  # Version history
├── ROADMAP.md                    # Planned features and priorities
└── COWORK.md                     # Session log for Cowork development

Hardware profiles included

Profile	Device
fortigate-120g	FortiGate 120G
fortigate-90g	FortiGate 90G
fortiswitch-224e-poe	FortiSwitch 224E-POE
fortiswitch-448e-fpoe	FortiSwitch 448E-FPOE
fortiswitch-624f	FortiSwitch 624F
fortiswitch-1024e	FortiSwitch 1024E
fortiap-431g	FortiAP 431G
fortiap-441k	FortiAP 441K

Adding reference material

Vendor docs are not included in the repo (they're proprietary). Place them in references/ organized by vendor — see references/README.md for the expected structure. The marker pipeline (marker/) can convert PDFs to markdown for ingestion.

License

MIT — see LICENSE.