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

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 files. According to the source code, these files contain the host invocation contract (lines 31-35 in skills/start-learning/SKILL.md) that specifies how commands should be formatted on different platforms.

Key skill files include:

• skills/start-learning/SKILL.md – Handles learner interview, placement quizzes, and initial state creation
• skills/learn/SKILL.md – Manages the interactive teaching loop, lesson fetching, and progress updates
• skills/learn-agent-skills/SKILL.md – Specialized tutor for the Agent Skills certification track
• 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, 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 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, 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.

# 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 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 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 to identify the next lesson in the sequence, then retrieves content from the phases/ directory structure—specifically phases/.../docs/en.md for lesson material and .../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

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 or MCP-LEARNING.md, it hands off control to specialized tutors:

# 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

# 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:

# 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 – Onboarding logic, interview flow, and initial state generation
• skills/learn/SKILL.md – Core tutoring engine with resume routing (lines 44-62) and lesson delivery
• skills/learn-agent-skills/SKILL.md – Agent Skills track implementation using learning-paths/agent-skills.json
• skills/learn-mcp/SKILL.md – Model Context Protocol specialization using learning-paths/model-context-protocol.json
• scripts/lesson_run.py – Host dispatcher that interprets commands and executes skills
• LEARNING.md (generated) – Persistent learner state driving resume behavior and progress tracking

Summary

• Portable skill definitions in 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 (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 or 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 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—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 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) and dispatch to your new tutor implementation.

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