How the AI Tutor Skill System Works for Claude Code and Codex

The AI tutor skill system uses portable SKILL.md bundles to expose host-specific commands—/learn for Claude Code and learn for Codex—while centrally managing curriculum logic, state routing, and automated quizzing across different learning routes.

The rohitg00/ai-engineering-from-scratch repository implements an AI tutor skill system that transforms supported hosts into interactive instructors for the AI Engineering from Scratch curriculum. By defining host-agnostic skill bundles with host-specific invocation contracts, the system allows learners to use natural slash-commands in Claude Code or plain skill names in Codex to navigate lessons, track progress, and validate understanding through automated assessments.

SKILL.md Structure and Host-Specific Contracts

Each skill is defined by a SKILL.md file that acts as both a manifest and an execution contract. According to the source code in skills/learn/SKILL.md, these files contain YAML front-matter describing the skill's name, description, and tags, followed by a host-specific invocation table that maps generic skill names to exact command syntax.

The host contract table (lines 22-30 in skills/learn/SKILL.md) defines how the same skill surfaces in different environments:

Host	Start or resume
Codex	learn, start-learning, check-understanding 13
Claude Code	/learn, /start-learning, /check-understanding 13

This mapping ensures that learners type learn in Codex but /learn in Claude Code, with the skill logic remaining identical underneath. The scripts/install_skills.py file (lines 4-19 and 24-31) discovers these SKILL.md bundles, validates their front-matter, and copies them into a target skills/ directory, enabling the same bundle to function across Claude Code, Codex, Cursor, or future hosts without modification.

State Routing and Progress Isolation

The AI tutor skill system maintains separate state files for different learning routes to prevent accidental merging of progress. As implemented in skills/learn/SKILL.md (lines 49-66), the skill examines existing progress files during invocation to determine which sub-skill to dispatch:

• LEARNING.md – tracks the full curriculum route
• MCP-LEARNING.md – tracks the Model Context Protocol specialization
• AGENT-SKILLS-LEARNING.md – tracks the Agent Skills pathway
• CLAUDE-CERTIFICATION.md – tracks certification progress

When a learner issues resume or continue, the system checks for these files and routes to the appropriate sub-skill (learn-mcp or learn-agent-skills). The learn-mcp skill follows the same pattern with its own SKILL.md (lines 22-27), enforcing route-specific state isolation through dedicated progress files.

The Three-Step Teaching Flow

The AI tutor skill system orchestrates a structured pedagogical loop defined in skills/learn/SKILL.md (lines 20-55). For each lesson phase, the skill reads the lesson markdown from phases/<phase>/<lesson>/docs/en.md and its corresponding quiz.json, then executes:

1. Warm-up recall – The tutor queries two random questions from the previous lesson to activate prior knowledge.

2. Teach the lesson – The skill presents a four-part sequence: problem statement → concept explanation → code walk-through → "use it" comparison, pausing at each stage for learner predictions.

3. Quiz assessment – The tutor asks all post-stage questions from quiz.json, records the score, and updates the progress file.

This flow runs identically regardless of whether the learner invoked the skill via Codex or Claude Code, ensuring consistent educational outcomes across hosts.

Host-Agnostic UI Rendering

The system adapts its interface layer to match the host's command syntax. In site/lesson.html (lines 5480-5490), the UI layer injects the appropriate command syntax based on the detected host. For Codex deployments, buttons display learn while Claude Code deployments show /learn, dynamically referencing the host contract tables defined in each SKILL.md.

Installing and Porting Skills

The scripts/install_skills.py script provides the installation mechanism that makes the AI tutor skill system portable. The script performs three operations:

• Discovers all SKILL.md bundles in the repository
• Validates front-matter metadata (name, description, tags)
• Copies validated skills into a target directory layout

# Install skills into a local repository for Claude Code or Codex consumption

python3 scripts/install_skills.py ./my-tutor \
    --type skill --layout skills --force

Because skill definitions are pure markdown with host contracts embedded, the same bundle can be dropped into any supported host without code changes. A minimal dispatcher stub could parse these files as follows:

from pathlib import Path

def dispatch_skill(command: str):
    # Normalize command by stripping leading slash for Claude Code compatibility

    skill_name = command.lstrip('/')
    # Locate the skill definition installed under ./my-tutor/<skill>/SKILL.md

    skill_path = Path("./my-tutor") / skill_name / "SKILL.md"
    # Parse front-matter and execute the skill logic

    run_skill(skill_path)

Usage Examples by Host

The AI tutor skill system adapts to the host's interface conventions while executing identical curriculum logic:

# In Claude Code (slash-command interface)

> /learn                # starts the full curriculum tutor

> /learn-mcp            # switches to the Model Context Protocol path

> /check-understanding 13   # quizzes on Phase 13

# In Codex (plain skill name interface)

> learn                 # starts the full curriculum tutor

> learn-mcp             # switches to the MCP path

> check-understanding 13   # quizzes on Phase 13

Summary

• Portable skill bundles – Each skill is a self-contained SKILL.md with front-matter metadata and embedded host contracts.
• Host-specific invocation – The same skill exposes /learn in Claude Code and learn in Codex through mapping tables.
• State isolation – Progress files (LEARNING.md, MCP-LEARNING.md) prevent route collision and enable accurate resume functionality.
• Standardized pedagogy – All hosts execute the same three-step flow: warm-up recall, structured lesson delivery, and quiz assessment.
• Universal installer – scripts/install_skills.py validates and deploys skills to any target directory for immediate host consumption.

Frequently Asked Questions

How does the AI tutor skill system handle different command syntaxes between Claude Code and Codex?

The system uses host contract tables embedded in each SKILL.md file (visible in skills/learn/SKILL.md lines 22-30) that map generic skill names to host-specific syntax. Claude Code uses slash-commands like /learn while Codex uses plain skill names like learn. The UI layer in site/lesson.html renders the appropriate syntax based on the detected host environment.

What prevents progress from different learning routes from mixing together?

The skill system maintains separate state files for each route: LEARNING.md for the full curriculum, MCP-LEARNING.md for the Model Context Protocol track, and AGENT-SKILLS-LEARNING.md for agent skills. When resuming, the skill examines these files (as implemented in skills/learn/SKILL.md lines 49-66) and dispatches to the correct sub-skill without merging states.

Can the AI tutor skill system work with hosts other than Claude Code and Codex?

Yes. The portable skill framework is designed for host-agnostic deployment. Because skills are defined in pure markdown with explicit host tables, new hosts can be supported by adding rows to the invocation tables without modifying the core curriculum logic. The install_skills.py script (lines 4-19) handles validation and installation for any compliant host.

How does the system select and present lesson content?

The skill reads lesson content from phases/<phase>/<lesson>/docs/en.md and assessments from quiz.json. It follows a fixed three-step sequence defined in skills/learn/SKILL.md: warm-up questions from previous material, structured lesson delivery with prediction pauses, and finally a scored quiz that updates the learner's progress file.

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