# Automation Scripts in the AI-Engineering-From-Scratch `scripts/` Directory

> Discover automation scripts in the rohitg00/ai-engineering-from-scratch repo. Learn about Python and Bash utilities for scaffolding, validation, testing, and metadata management.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-20

---

**The `scripts/` directory contains nine lightweight, self-contained utilities written in pure Python and Bash that automate lesson scaffolding, link validation, code execution testing, and curriculum metadata management without requiring external dependencies.**

The `rohitg00/ai-engineering-from-scratch` repository maintains a strict "std-lib-only" philosophy for its tooling. The **automation scripts in the `scripts/` directory** handle the complete lifecycle of the curriculum—from generating consistent lesson skeletons to validating external links and compiling machine-readable catalogs. These utilities run independently of heavy ML libraries and integrate directly with the CI pipeline defined in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml).

## Lesson Scaffolding and Workbench Setup

### [`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py)

This Python utility copies the pre-built **Agent Workbench** pack into a target repository. It optionally seeds [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) and [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) files to initialize an autonomous agent environment. According to the source code, this script acts as the entry point for building agentic workspaces that feed into the builder agent architecture.

### [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh)

Written in Bash, this helper creates uniform skeletons for new lessons. It generates the standard directory layout—including `code/`, `docs/`, and `outputs/` subdirectories—along with starter documentation and code stubs. This guarantees that every contribution follows the repository's organizational conventions.

## Validation and Quality Assurance

### [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py)

This validator traverses every Markdown file in the repository, extracts HTTP/HTTPS URLs, and verifies them using **HEAD** and **GET** requests. It caches results for seven days to optimize performance and can be restricted to specific phases or output JSON for CI integration.

### [`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py)

This script performs syntax-only compilation of all Python lesson files to detect import errors or malformed code. When invoked with execution flags, it runs each lesson’s entry script with a timeout, automatically skipping lessons that require heavy dependencies to maintain fast feedback loops.

### [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)

Acting as the primary static-analysis gate, this script enforces curriculum-wide invariants across every lesson. It validates file naming conventions, documentation front-matter, and quiz schema compliance, exiting with error codes suitable for CI rejection of policy violations.

## Metadata and Curriculum Management

### [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)

This utility verifies that the top-level [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) accurately reflects the current number of lessons in each phase. It identifies discrepancies between documented counts and the actual source tree, with an optional `--fix` flag to automatically synchronize the table.

### [`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py)

This generator creates [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json), a machine-readable index of all lessons written to the repository root. The catalog feeds the site-generation pipeline ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) with up-to-date metadata, enabling automated documentation builds.

### [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py)

This installer handles "skill" artifacts produced by lessons, copying files from individual `outputs/` directories into a central workspace. It facilitates reusable components—such as prompts and agent configurations—across different phases of the curriculum.

## Shared Utilities

### [`scripts/_lib.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/_lib.py)

This module provides common helper functions consumed by other scripts in the directory. It includes colored terminal output for readability and path utilities to standardize file operations across the automation suite.

## How to Run the Automation Scripts

All scripts execute from the repository root and require only Python 3 or Bash. Below are the standard invocations extracted from the source docstrings.

Scaffold the Agent Workbench into a new repository:

```bash
python3 scripts/scaffold_workbench.py /path/to/your/repo \
    --force      # overwrite existing files

    --minimal    # only copy core files, skip docs/

    --dry-run    # preview actions without writing

```

Create a new lesson skeleton:

```bash
scripts/scaffold-lesson.sh 14-agent-engineering 03-agent-workbench "Agent Workbench"

```

Validate external Markdown links with optional caching and strict mode:

```bash
python3 scripts/link_check.py               # full repo check

python3 scripts/link_check.py --phase 14    # limit to phase 14 only

python3 scripts/link_check.py --strict       # exit 1 on any broken link

python3 scripts/link_check.py --json         # machine-readable output

```

Smoke-check lesson Python code for syntax errors or execute with timeouts:

```bash
python3 scripts/lesson_run.py                # syntax-only check

python3 scripts/lesson_run.py --execute      # run each lesson (skip heavy deps)

python3 scripts/lesson_run.py --strict        # fail CI on any error

python3 scripts/lesson_run.py --json          # JSON report

```

Install skill artifacts from a specific phase:

```bash
python3 scripts/install_skills.py --phase 14

```

Verify and auto-fix README lesson counts:

```bash
python3 scripts/check_readme_counts.py        # prints mismatches

python3 scripts/check_readme_counts.py --fix   # auto-fix README counts

```

Generate the lesson catalog:

```bash
python3 scripts/build_catalog.py

```

Run the full curriculum audit:

```bash
python3 scripts/audit_lessons.py

```

## Summary

- The **`scripts/`** directory contains nine automation utilities that operate without external dependencies, adhering to the repository's "std-lib-only" philosophy.
- **Scaffolding scripts** ([`scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold_workbench.py), [`scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh)) initialize consistent lesson structures and agent workbench environments.
- **Validation scripts** ([`link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/link_check.py), [`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py), [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py)) enforce code quality, check external references, and verify curriculum compliance.
- **Management scripts** ([`build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/build_catalog.py), [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py), [`install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py)) synchronize metadata and distribute reusable artifacts across the curriculum.
- All scripts integrate with the CI workflow at [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) and can be invoked individually from the repository root.

## Frequently Asked Questions

### Do the automation scripts require external Python packages?

No. According to the source code, every script in the `scripts/` directory is implemented using only the Python standard library or standard Bash utilities. This design ensures portability and allows the scripts to run in minimal CI environments without installing heavy ML dependencies.

### How does [`link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/link_check.py) optimize performance when validating URLs?

The script implements a seven-day disk cache for HTTP responses. When checking links in [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py), it stores previous HEAD and GET request results, avoiding redundant network calls during subsequent validation runs. This caching mechanism is critical for maintaining fast CI feedback loops across the entire curriculum.

### What is the difference between [`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py) and [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py)?

[`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py) focuses on executable correctness, performing syntax compilation and optionally running lesson entry points with timeouts to catch runtime errors. In contrast, [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) performs static analysis of repository structure, enforcing policy rules like file naming conventions, front-matter schema, and quiz validation without executing code.

### How do I create a new lesson using the provided scaffolding tools?

First, run [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) with the phase number, lesson number, and title to generate the directory structure. Then, if the lesson produces reusable agent components, use `python3 scripts/install_skills.py` to publish those artifacts from the lesson's `outputs/` directory to the central workspace. This workflow ensures new content follows the established organizational standards.