# What Does the `scaffold-lesson.sh` Automation Script Do? > Discover what the scaffold-lesson.sh automation script does for the AI Engineering From Scratch repository. It creates standardized lesson structures to ensure consistency and streamline development. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: how-to-guide - Published: 2026-06-07 --- **The [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) automation script generates a standardized lesson skeleton—complete with directories, starter markdown, and a Python stub—for the *AI Engineering From Scratch* repository, ensuring every new lesson follows the curriculum's strict layout conventions.** The [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) automation script lives in the `scripts/` directory of the open-source `rohitg00/ai-engineering-from-scratch` curriculum. Its primary purpose is to eliminate repetitive manual setup and enforce the repository's **one-commit-per-lesson** rule across all 435 lessons. When contributors invoke the script, it validates inputs, resolves paths from the repository root, generates a consistent folder hierarchy, and prints a checklist for the remaining manual steps. ## Usage and Basic Syntax The script accepts two required arguments and one optional argument: a phase directory, a lesson slug in `NN-kebab-case` format, and an optional human-readable title. If arguments are missing or malformed, it prints a usage help block (lines 4–15). ```bash # Create lesson 03-tokenizers in the NLP foundations phase scripts/scaffold-lesson.sh 05-nlp-foundations-to-advanced 03-tokenizers # Provide an optional title for richer metadata scripts/scaffold-lesson.sh 05-nlp-foundations-to-advanced 03-tokenizers "Tokenizers from Scratch" ``` After a successful run, the terminal displays a summary and a four-step checklist: ```text created phases/05-nlp-foundations-to-advanced/03-tokenizers/ next: 1. edit phases/05-nlp-foundations-to-advanced/03-tokenizers/docs/en.md 2. write phases/05-nlp-foundations-to-advanced/03-tokenizers/code/main.py 3. add a markdown-link row to ROADMAP.md … 4. atomic commit: git add phases/… ROADMAP.md && git commit -m "feat(phase-05/03): Tokenizers from Scratch" ``` ## How the Script Works The [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) automation script processes each lesson request through a rigid, eight-step pipeline. ### Input Validation First, the script verifies that the caller supplied a phase directory, a properly formatted lesson slug, and optionally a title. When these are absent, it exits early and surfaces the built-in help text (lines 4–15). This gate prevents incomplete or malformed lesson entries from ever touching the filesystem. ### Repository Root and Path Resolution The script locates the repository root via `git rev-parse` (line 22). It then computes absolute paths for the target phase and the new lesson directory (lines 28–30). Anchoring everything to the Git root guarantees that the script behaves correctly regardless of the caller's current working directory. ### Pre-Condition Checks Before creating any files, the script enforces three hard constraints (lines 31–45): - The target **phase directory** must already exist. - The **lesson slug** must match the `NN-kebab-case` pattern. - The **lesson directory** must not already exist. If any check fails, the script aborts immediately and reports the specific violation. ### Directory Creation Once validation passes, the script creates the required folder hierarchy under `phases//` (line 47). Every new lesson receives four standardized subdirectories: - `code/` – Python source files - `notebook/` – Jupyter notebooks - `docs/` – curriculum markdown - `outputs/` – generated artifacts ### Generating Starter Files The [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) automation script populates the new tree with three categories of starter content: **Curriculum Markdown.** It writes a fully templated [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) (lines 57–116) that includes the repository's mandated front-matter specification. Authors open this file and fill in lesson objectives, theory, and exercises without worrying about metadata formatting. **Python Stub.** It drops a minimal [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) (lines 118–125) containing a single stub that raises `NotImplementedError`. This explicit placeholder reminds contributors exactly where to implement the lesson logic. **Git Placeholders.** To ensure Git tracks the otherwise empty `notebook/` and `outputs/` directories, the script touches placeholder files inside them (lines 127–128). ### Post-Creation Checklist Finally, the script prints a numbered checklist (lines 30–38) that guides the contributor through the remaining manual workflow: editing the markdown, writing the Python implementation, appending the lesson row to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and committing atomically. ## Key Files in the Scaffolding Workflow The entire lesson-generation pipeline revolves around four critical paths in the `rohitg00/ai-engineering-from-scratch` repository: - **[`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh)** – The automation script itself. - **`phases///docs/en.md`** – The templated curriculum file created by the script. - **`phases///code/main.py`** – The `NotImplementedError` stub generated for every lesson. - **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** – The master index where contributors must manually link the new lesson after scaffolding. ## Summary - The [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) automation script validates phase directories, lesson slugs, and optional titles before any filesystem changes occur. - It resolves absolute paths from the Git repository root and enforces the `NN-kebab-case` naming convention. - The script creates a uniform four-directory hierarchy (`code`, `notebook`, `docs`, `outputs`) for every lesson. - It auto-generates a front-matter-ready [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), a `NotImplementedError` stub in [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py), and Git-safe placeholder files. - A printed post-creation checklist reminds contributors to update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) and commit atomically, preserving the one-commit-per-lesson policy. ## Frequently Asked Questions ### What arguments are required to run [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh)? The script requires a phase directory name and a lesson slug in `NN-kebab-case` format. An optional third argument supplies a human-readable title. If required arguments are missing, the script exits and prints usage help defined in lines 4–15. ### What directory structure does the script create? The script creates four subdirectories under `phases///`: `code/`, `notebook/`, `docs/`, and `outputs/`. This layout is hard-coded in the script (line 47) and guarantees every lesson in the 435-lesson repository follows identical architectural conventions. ### Why does the generated [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) raise `NotImplementedError`? According to lines 118–125 of [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh), the script intentionally emits a minimal Python stub containing `raise NotImplementedError`. This serves as an explicit reminder for the contributor to implement the lesson logic before submission. ### How does [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh) enforce the NN-kebab-case naming rule? During pre-condition checks (lines 31–45), the script validates the lesson slug against the `NN-kebab-case` pattern. If the slug violates this convention or if the target lesson directory already exists, the script aborts immediately and reports the error to the caller.