# How to Integrate AI Tutor Skills with Agents: start-learning and learn Explained

> Discover how AI Tutor skills integrate with agents. Learn how start-learning initializes state and learn delivers interactive lessons, orchestrated by a dispatcher.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-08-31

---

**AI Tutor skills integrate with agents through a portable skill system where `start-learning` handles onboarding and state initialization while `learn` manages interactive lesson delivery, both orchestrated by a host dispatcher that reads SKILL.md definitions and persists learner state in markdown files.**

The rohitg00/ai-engineering-from-scratch repository implements a lightweight skill architecture that enables any LLM-backed agent—whether Codex, Claude Code, or custom hosts—to drive interactive tutoring experiences. This system uses declarative skill definitions and persistent state files to create seamless handoffs between onboarding and lesson delivery without requiring host-specific code changes.

## Core Architecture of Skill-Agent Integration

### Skill Definitions and Host Contracts

The integration centers on **portable skill definitions** stored in [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) files. According to the source code, these files contain the *host invocation contract* (lines 31-35 in [`skills/start-learning/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/start-learning/SKILL.md)) that specifies how commands should be formatted on different platforms.

**Key skill files** include:

- [`skills/start-learning/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/start-learning/SKILL.md) – Handles learner interview, placement quizzes, and initial state creation
- [`skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn/SKILL.md) – Manages the interactive teaching loop, lesson fetching, and progress updates
- [`skills/learn-agent-skills/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn-agent-skills/SKILL.md) – Specialized tutor for the Agent Skills certification track
- [`skills/learn-mcp/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn-mcp/SKILL.md) – Dedicated tutor for the Model Context Protocol pathway

### State Management and Resume Routing

The system maintains **persistent learner state** through markdown files that act as resumable checkpoints. The primary state file, [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md), stores the learner's progress log, review queue, and phase status.

When a skill executes, it performs **resume routing** (lines 44-62 in both SKILL files) to determine whether to initialize a new learning session or continue an existing one. If [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) exists, `start-learning` summarizes existing progress and offers continuation options (lines 93-101). For new learners, it conducts an interview and placement quiz, then generates the state file.

## The Integration Flow: From Command to Lesson

### Step 1: Command Dispatch and Skill Resolution

The host dispatcher, implemented in [`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py), serves as the entry point for all skill invocations. When a user issues a command like `start-learning` (Codex) or `/start-learning` (Claude Code), the dispatcher normalizes the syntax and locates the corresponding SKILL definition.

```python

# scripts/lesson_run.py (simplified flow)

def dispatch(command):
    name, *args = command.split()
    skill_path = f"skills/{name}/SKILL.md"
    skill = load_skill(skill_path)          # parses the front-matter

    host_form = skill["Host invocation contract"]
    run_skill(skill, args)

```

### Step 2: Onboarding with start-learning

The `start-learning` skill executes a structured onboarding process (steps 5-7 in its SKILL definition). First, it checks for existing state files. If [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) exists, the skill summarizes the learner's current progress and offers resume options. For new learners, it conducts an interview and placement quiz, then generates a fresh [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) file containing the learner's profile and initial route mapping.

### Step 3: Lesson Delivery with learn

After onboarding, control transfers to the `learn` skill via the resume routing logic. This skill reads [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) to identify the next lesson in the sequence, then retrieves content from the `phases/` directory structure—specifically [`phases/.../docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/.../docs/en.md) for lesson material and [`.../quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.../quiz.json) for assessments.

The skill executes an interactive teaching loop (steps 0-5) that:

1. Runs warm-up recall exercises
2. Delivers the lesson content
3. Administers quizzes
4. Updates the learner's progress log and review queue
5. Persists all changes back to [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md)

### Step 4: Sub-skill Routing for Specialized Tracks

For learners pursuing specific certifications, the system supports **portable sub-skills**. When the resume routing logic detects track-specific state files like [`AGENT-SKILLS-LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENT-SKILLS-LEARNING.md) or [`MCP-LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/MCP-LEARNING.md), it hands off control to specialized tutors:

```python

# Resume routing pseudo-code (lines 44-62 in learn/SKILL.md)

if "AGENT-SKILLS-LEARNING.md" in state_files:
    # Route to Agent Skills tutor using learning-paths/agent-skills.json

    run_skill(load_skill("skills/learn-agent-skills/SKILL.md"), [])
elif "MCP-LEARNING.md" in state_files:
    # Route to MCP tutor using learning-paths/model-context-protocol.json

    run_skill(load_skill("skills/learn-mcp/SKILL.md"), [])

```

## Implementation Examples

### CLI Invocation Patterns

```bash

# Fresh onboarding (Codex host)

$ start-learning

# → Executes interview, placement quiz, generates LEARNING.md

# Resume existing session (Claude Code host)

$ /learn

# → Reads LEARNING.md, selects next lesson, begins interactive tutor

```

### JSON-RPC Style Integration

Agents can invoke skills programmatically using the same definitions:

```python

# Dispatcher handles routing to sub-skills automatically

def handle_resume(state_files):
    if track == "agent-skills":
        # Loads five-lesson path from learning-paths/agent-skills.json

        return invoke_subskill("learn-agent-skills")

```

## Key Files in the Integration Layer

- **[`skills/start-learning/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/start-learning/SKILL.md)** – Onboarding logic, interview flow, and initial state generation
- **[`skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn/SKILL.md)** – Core tutoring engine with resume routing (lines 44-62) and lesson delivery
- **[`skills/learn-agent-skills/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn-agent-skills/SKILL.md)** – Agent Skills track implementation using [`learning-paths/agent-skills.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/agent-skills.json)
- **[`skills/learn-mcp/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn-mcp/SKILL.md)** – Model Context Protocol specialization using [`learning-paths/model-context-protocol.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/model-context-protocol.json)
- **[`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py)** – Host dispatcher that interprets commands and executes skills
- **[`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md)** (generated) – Persistent learner state driving resume behavior and progress tracking

## Summary

- **Portable skill definitions** in [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) files allow the same tutoring logic to run on Codex, Claude Code, or any compatible host without modification
- **`start-learning`** initializes learner state through interviews and quizzes, writing progress to [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) (steps 5-7)
- **`learn`** reads state files to determine the next lesson, fetches content from `phases/`, and executes interactive teaching loops (steps 0-5)
- **Resume routing** (lines 44-62 in SKILL files) enables seamless continuation of interrupted sessions and automatic handoffs to specialized sub-skills
- **State-driven architecture** persists all learner progress in markdown files, enabling cross-session continuity and track-specific routing

## Frequently Asked Questions

### How does the agent determine which skill to execute next?

The agent uses **resume routing logic** embedded in the SKILL.md files (specifically lines 44-62) to check for existing state files like [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md) or [`AGENT-SKILLS-LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENT-SKILLS-LEARNING.md). If the learner has an active session, the skill summarizes progress and continues the appropriate track. If the user switches tracks or starts fresh, the routing logic hands off to `start-learning` or a specialized sub-skill accordingly.

### What makes these AI Tutor skills portable across different agent hosts?

The skills rely on a **host invocation contract** (defined in lines 31-35 of the SKILL definitions) rather than host-specific code. This contract specifies command syntax normalization—such as converting `/learn` (Claude Code) or `start-learning` (Codex) into standard invocations—while the core logic remains pure data. Any dispatcher implementing this contract, whether [`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py) or a custom web service, can execute the skills unchanged.

### How is learner progress maintained between sessions?

Progress persists in **markdown state files**—primarily [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LEARNING.md)—which store the learner's current phase, review queue, and route selection. When a learner resumes, the `learn` skill reads this file to reconstruct the session state, fetch the next lesson from the `phases/` directory, and continue the interactive loop exactly where the user left off.

### Can the system support custom learning tracks beyond Agent Skills and MCP?

Yes, the architecture supports extension through new **portable sub-skills**. You can create a new skill directory under `skills/`, define its routing rules in a [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) file following the host invocation contract, and add a corresponding JSON curriculum file in `learning-paths/`. The resume routing logic will automatically detect track-specific state files (such as [`CUSTOM-TRACK-LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CUSTOM-TRACK-LEARNING.md)) and dispatch to your new tutor implementation.