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

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.

Lesson Scaffolding and Workbench Setup

scripts/scaffold_workbench.py

This Python utility copies the pre-built Agent Workbench pack into a target repository. It optionally seeds task_board.json and 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

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

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

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

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

This utility verifies that the top-level 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

This generator creates catalog.json, a machine-readable index of all lessons written to the repository root. The catalog feeds the site-generation pipeline (site/build.js) with up-to-date metadata, enabling automated documentation builds.

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

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:

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:

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

Validate external Markdown links with optional caching and strict mode:

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:

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:

python3 scripts/install_skills.py --phase 14

Verify and auto-fix README lesson counts:

python3 scripts/check_readme_counts.py        # prints mismatches

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

Generate the lesson catalog:

python3 scripts/build_catalog.py

Run the full curriculum audit:

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, scaffold-lesson.sh) initialize consistent lesson structures and agent workbench environments.
• Validation scripts (link_check.py, lesson_run.py, audit_lessons.py) enforce code quality, check external references, and verify curriculum compliance.
• Management scripts (build_catalog.py, check_readme_counts.py, install_skills.py) synchronize metadata and distribute reusable artifacts across the curriculum.
• All scripts integrate with the CI workflow at .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 optimize performance when validating URLs?

The script implements a seven-day disk cache for HTTP responses. When checking links in 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 and audit_lessons.py?

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}