How MCP-LEARNING.md Tracks Progress in the MCP Route: A Complete Technical Guide

MCP-LEARNING.md operates as a plain-text state file that employs a "locate-or-create" policy, a markdown progress table with five columns, and dedicated evidence sections to persist learner advancement through the 17-lesson Model Context Protocol curriculum in the rohitg00/ai-engineering-from-scratch repository.

The learn-mcp skill in the rohitg00/ai-engineering-from-scratch repository treats MCP-LEARNING.md as the single source of truth for tracking progress through the MCP learning route. By storing state in a human-readable markdown format rather than a binary database, the system ensures version control compatibility, manual editability, and seamless integration with downstream tooling such as the site generator.

The Locate-or-Create State File Policy

When the learn-mcp skill initializes, it implements a strict discovery protocol to locate the learner's existing progress file. According to skills/learn-mcp/SKILL.md (lines 80-88), the skill first checks for the presence of MCP-LEARNING.md in the workspace root. If the file is absent, the system performs an atomic rename check for the legacy filename MCP-ENGINEERING-LEARNING.md, migrating it to the canonical name to maintain continuity without data loss.

If neither file exists, the skill generates a new MCP-LEARNING.md with a standardized template containing a static header, an empty progress table, and placeholder sections for evidence collection. This initialization guarantees that every subsequent operation has a persistent target for state mutations.

Legacy File Migration Handling

The migration logic specifically checks for the older filename to accommodate learners who began the curriculum before the naming standardization. By renaming rather than copying, the operation preserves file system metadata and ensures that external references (such as editor bookmarks or shell history) remain valid while consolidating the state into the modern naming convention.

Markdown Table Schema for Progress Tracking

The core of MCP-LEARNING.md contains a Progress table (lines 22-24 of the generated file) that functions as a persistent ledger. Each row in this table tracks a specific lesson from the 17-lesson curriculum and contains five distinct columns:

• Order – The lesson index derived from the manifest sequence
• Lesson – The human-readable title (e.g., "13/06 MCP fundamentals")
• Status – The current state in the lesson lifecycle
• Evidence – A tag indicating whether executable or conceptual proof has been collected
• Completed – A timestamp placeholder for finish time

This tabular structure enables both automated parsing and manual inspection, allowing learners to view their standing at a glance.

Status State Machine Transitions

The Status column operates as a finite state machine with four valid states: Next, In progress, Locked, and Done. When a learner initiates a lesson, the skill locates the first row marked Next and transitions it to In progress. Upon completion, the status advances to Done, and the subsequent row automatically promotes from Locked to Next. This enforced sequencing prevents learners from skipping foundational lessons while clearly indicating the current active task.

Resume Semantics and Lesson Advancement

The skill implements intelligent resume semantics (lines 93-99 in SKILL.md) that scan the progress table on every invocation to determine the appropriate starting point. The algorithm searches for the first row containing either In progress or Next, designating that lesson as the active target. All preceding rows must already display Done status; if the scan finds any inconsistency (such as a Done row followed by a Locked row), the skill can trigger repair logic to restore the sequence.

When a lesson reaches completion, the skill performs three atomic operations: it updates the row status to Done, appends a timestamp to the Completed column, and promotes the next sequential row from Locked to Next. If every required lesson already shows Done, the skill transitions to checking optional capstone prerequisites rather than restarting the route (lines 95-96).

Evidence Capture and Auditability

Beyond simple status tracking, MCP-LEARNING.md maintains two specialized sections for detailed evidence collection: Wire evidence and Notes. The Wire evidence section stores concrete execution data including command strings, current working directories (cwd), exit codes, request identifiers, and output snippets. The Notes section accommodates free-form observations, conceptual summaries, and troubleshooting records.

After each lesson checkpoint, the skill populates these sections with structured markdown, ensuring that progress remains auditable and reproducible (lines 61-68 and 122-131). This design supports both the learner's future reference and potential validation by automated assessment tools.

Integration with the Learning Path Manifest

The ordering of rows in the Progress table derives directly from learning-paths/model-context-protocol.json (lines 37-40), which specifies the ordered list of lesson identifiers (e.g., 06, 07, 08 … 31). The skill reads this manifest during initialization to generate the table structure, ensuring that the physical file layout matches the curriculum's pedagogical sequence. This manifest-driven approach decouples the state file format from the curriculum content, allowing the learning path to evolve without requiring changes to the progress tracking logic.

The site generator referenced in site/data.js (line 6904) consumes MCP-LEARNING.md to surface real-time progress indicators in the generated UI, demonstrating how the plain-text format enables interoperability between the learning skill and external tooling.

Summary

• MCP-LEARNING.md serves as the canonical state file for the learn-mcp skill, implementing a "locate-or-create" policy that includes legacy file migration from MCP-ENGINEERING-LEARNING.md.
• Progress tracking relies on a markdown table with five columns (Order, Lesson, Status, Evidence, Completed) that maps to the 17-lesson sequence defined in learning-paths/model-context-protocol.json.
• The status field operates as a state machine (Locked → Next → In progress → Done) with resume semantics that automatically identify the current active lesson on skill invocation.
• Wire evidence and Notes sections capture executable proof and conceptual observations, creating an auditable trail of the learning journey.
• The plain-text format enables version control, manual editing, and integration with downstream tools like the site generator while maintaining strict ordering constraints through manifest-driven initialization.

Frequently Asked Questions

What happens if I delete MCP-LEARNING.md mid-course?

If you delete the file, the learn-mcp skill will regenerate it using the template from skills/learn-mcp/SKILL.md upon the next invocation. However, you will lose your historical progress records, evidence entries, and completion timestamps. The skill cannot reconstruct your previous state from the learning-paths/model-context-protocol.json manifest alone, as that file only contains lesson identifiers, not learner-specific progress data.

Can I manually edit the progress table to skip lessons?

While the markdown format allows manual editing, bypassing the Locked → Next → In progress → Done sequence may cause the resume semantics to behave unpredictably. The skill expects exactly one Next or In progress row at any given time, with all prior rows marked Done. Manual alterations that violate this invariant could result in the skill selecting the wrong lesson or triggering repair logic that resets the table to a known good state.

How does the skill handle concurrent modifications to the file?

The skill does not implement file locking or atomic transaction mechanisms for MCP-LEARNING.md. If multiple processes modify the file simultaneously, the last write operation will prevail, potentially resulting in lost updates or malformed markdown tables. For best results, ensure only one instance of the learn-mcp skill operates against the state file at any given time.

What distinguishes Wire evidence from the Notes section?

Wire evidence captures objective, executable proof such as command outputs, exit codes, and request IDs that demonstrate the learner successfully executed specific MCP operations. The Notes section stores subjective, free-form content including conceptual explanations, troubleshooting steps, and personal observations. The skill treats Wire evidence as validation artifacts for lesson completion, while Notes serve as supplementary documentation for the learner's reference.

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