How the 'Skills' System Provides Interactive Tutoring in AI Engineering From Scratch

The 'skills' system in rohitg00/ai-engineering-from-scratch transforms static curriculum files into a live, step-by-step tutor through a host-invocation contract defined in SKILL.md files that orchestrates five distinct learning stages—from state location to interactive quizzing.

The repository implements a modular tutoring engine where each skill operates as a deterministic, sandboxed module. This interactive tutoring skills system enables learners to engage with AI engineering concepts through structured, adaptive sessions that persist progress and validate understanding in real time.

The Skill Contract Architecture

At the core of the interactive capabilities lies the host-invocation contract specified in each SKILL.md file. For example, skills/learn/SKILL.md defines the protocol that the learner's CLI or web UI must follow to execute a tutoring session.

The contract specifies three critical elements:

• Invocation Protocol: How the host script (scripts/lesson_run.py) initiates the skill
• Input/Output Specifications: Expected parameters and return structures
• Routing DSL: Directives for switching between "learn", "resume", and "check-understanding" modes

Tags such as [tutor, curriculum, interactive-learning] embedded in the skill metadata enable discoverability through the generic learn command. This allows the host to locate and execute appropriate tutoring modules dynamically without hardcoding specific lesson paths.

The Five-Stage Tutoring Flow

The interactive tutoring experience follows a rigorous five-stage pipeline defined in skills/learn/SKILL.md, ensuring consistent pedagogical delivery across all lessons.

1. Locate State

The skill first queries persisted learner state to determine which lessons have been completed. This allows the tutor to resume exactly where the user left off, retrieving progress records from the outputs/skills/ directory before presenting new material.

2. Warm-up Recall

If previous lesson data exists, the system activates memory reactivation protocols. The tutor poses a quick recall question to prime the learner's existing knowledge before introducing new concepts, ensuring cognitive continuity across sessions.

3. Teach the Lesson

The core pedagogical phase presents lesson content through an interactive dialogue. Learners type responses to prompts, and the tutor validates these inputs before proceeding. The skill only advances after explicit confirmation of understanding, creating a mastery-based progression loop.

4. Interactive Quiz

Immediately following instruction, the system administers a six-question assessment using the AskUserQuestion tool. The quiz structure consists of:

1. One pre-check question
2. Three checkpoint questions
3. Two post-check questions

Each question renders individually, requiring typed responses rather than multiple-choice selection, ensuring active recall rather than passive recognition.

5. Record and Close

The final stage persists learner answers, timestamps, and generated artifacts to the progress file in outputs/skills/. The skill then executes a clean exit, releasing resources and preparing the environment for the subsequent lesson invocation.

Host Implementation and Invocation

The scripts/lesson_run.py file serves as the host runtime that parses skill contracts and drives the interactive loop. This script mediates between the learner interface and the skill definitions, handling state management and I/O operations.

Command-Line Invocation

Learners initiate tutoring sessions directly from the repository root:

# Start a tutoring session

python3 scripts/lesson_run.py learn

The tutor pauses for input after each pedagogical step:

> Warm-up: What is the purpose of a forward pass? <type answer>
> Teaching: ... (lesson content appears)
> Quiz: Question 1 – … (type answer)

Programmatic Integration

External Python tools can invoke the same contract through the pseudo-API exposed by the host script:

from skills.learn import invoke_skill

result = invoke_skill(
    mode="learn",
    lesson_slug="07-transformers-deep-dive/04-positional-encoding"
)
print(result["status"])  # → "completed"

Extending the Tutoring System

Because each skill is deterministic, self-tested, and sandboxed, the tutoring framework supports horizontal expansion without architectural changes. New domains require only a new SKILL.md file following the established contract.

The repository demonstrates this extensibility through specialized skill implementations:

• skills/learn-mcp/SKILL.md: Focused interactive tutor for Model-Context-Protocol concepts
• skills/learn-agent-skills/SKILL.md: Dedicated module for Agent-Skills curriculum paths

These extensions inherit the same five-stage tutoring flow and state persistence mechanisms while targeting distinct technical domains.

Summary

• The skills system uses SKILL.md contracts to define interactive tutoring protocols that the host script scripts/lesson_run.py executes.
• Each tutoring session follows a five-stage pipeline: state location, warm-up recall, interactive teaching, quiz assessment, and progress recording.
• The sandboxed, deterministic architecture ensures reproducible learning experiences across environments while supporting extensibility through new skill definitions.
• Learner progress persists to outputs/skills/ enabling session continuity and longitudinal tracking of mastery.

Frequently Asked Questions

How does the skills system remember where I left off?

The system maintains persisted state files in the outputs/skills/ directory. During the Locate State stage, skills/learn/SKILL.md queries these records to identify completed lessons and resume at the exact point of interruption, preserving your progress across multiple study sessions.

What makes the quiz component truly interactive rather than static?

Unlike static multiple-choice assessments, the quiz uses the AskUserQuestion tool to require typed, free-text responses to six sequentially presented questions. This design forces active recall and allows the tutor to evaluate conceptual understanding rather than pattern matching.

Can I create custom tutoring modules for other AI topics?

Yes. The architecture supports extension by creating new SKILL.md files that implement the host-invocation contract. Examples like skills/learn-mcp/SKILL.md demonstrate how to apply the five-stage tutoring flow to specialized domains while maintaining compatibility with scripts/lesson_run.py.

Is the tutoring system safe to run in automated environments?

The skills framework includes a non-interactive safety mode through sandboxed execution permissions. This deterministic behavior ensures that skills execute predictably without side effects, making them suitable for CI/CD pipelines or automated testing environments while preserving interactive capabilities for human learners.

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