How to Resolve State File Conflicts When LEARNING.md, MCP‑LEARNING.md, and AGENT‑SKILLS‑LEARNING.md Coexist

When multiple state files exist in your working directory, invoke the specific skill you want to use—learn, learn‑mcp, or learn‑agent‑skills—and the curriculum engine will automatically select the correct file without overwriting the others.

The AI Engineering from Scratch repository uses isolated persistent state files to track learner progress across distinct curriculum tracks. When LEARNING.md, MCP‑LEARNING.md, and AGENT‑SKILLS‑LEARNING.md appear simultaneously in your project root, this indicates active sessions on multiple skills rather than a filesystem collision that requires manual merging.

Understanding the Three State Files

Each state file belongs to a specific skill and serves a distinct pedagogical purpose:

• LEARNING.md – Owned by the learn skill (full curriculum). Stores your personalized study plan for the comprehensive AI engineering track.

• MCP‑LEARNING.md – Owned by the learn‑mcp skill. Tracks progress through the 17‑lesson Model‑Context‑Protocol manifest. The system also checks for the legacy filename MCP‑ENGINEERING‑LEARNING.md.

• AGENT‑SKILLS‑LEARNING.md – Owned by the learn‑agent‑skills skill. Holds checkpoint data for the five‑lesson Agent‑Skills track.

These files are deliberately isolated so that each skill can resume its own route without interfering with others. As documented in skills/start‑learning/SKILL.md (lines 46‑51), the curriculum engine treats these as independent routing targets rather than competing versions of the same data.

How the Repository Handles State File Selection

The conflict resolution logic is skill‑driven. When you invoke a specific skill, it queries only its designated state file and ignores the others entirely.

According to skills/learn/SKILL.md (lines 54‑59), the learn skill strictly operates on LEARNING.md. Similarly, skills/learn‑agent‑skills/SKILL.md (line 65) points exclusively to AGENT‑SKILLS‑LEARNING.md.

The learn‑mcp skill contains the most complex resolution flow, detailed in skills/learn‑mcp/SKILL.md (lines 82‑86):

1. If MCP‑LEARNING.md exists, use it immediately.
2. If the legacy MCP‑ENGINEERING‑LEARNING.md exists and MCP‑LEARNING.md does not, rename the legacy file to MCP‑LEARNING.md before proceeding.
3. Never touch LEARNING.md or AGENT‑SKILLS‑LEARNING.md.

This guarantees that only the relevant state file is read or written, leaving unrelated curriculum progress untouched.

Conflict Resolution Strategy

Do not manually merge the content of these files. They serve different curricula with incompatible internal structures. Deleting the wrong file will permanently erase progress for that specific track.

Instead, keep all three files in your working directory. The skill you invoke will automatically select the appropriate state file based on the mapping above. The logic functions similarly to this Python pseudo‑implementation found in the skill handlers:

import os
import shutil

def resolve_state_file(skill):
    if skill == "learn":
        return "LEARNING.md"
    if skill == "learn-mcp":
        # Prefer current name, fall back to legacy and rename

        if os.path.exists("MCP-LEARNING.md"):
            return "MCP-LEARNING.md"
        if os.path.exists("MCP-ENGINEERING-LEARNING.md"):
            shutil.move("MCP-ENGINEERING-LEARNING.md", "MCP-LEARNING.md")
            return "MCP-LEARNING.md"
    if skill == "learn-agent-skills":
        return "AGENT-SKILLS-LEARNING.md"
    raise ValueError("Unknown skill")

The real skill implementations in skills/learn‑mcp/ and skills/learn/ embed this logic directly, ensuring that file selection happens transparently before any lesson content loads.

Resetting a Specific Track

If you need to restart a single curriculum track without affecting others, remove only that track’s state file and rerun the corresponding skill:

# To reset only the MCP track

rm MCP-LEARNING.md

# Then rerun the skill to recreate the file from scratch

This targeted deletion allows you to reset the learn‑mcp track while preserving your progress in learn or learn‑agent‑skills.

Summary

• Coexistence is intentional: LEARNING.md, MCP‑LEARNING.md, and AGENT‑SKILLS‑LEARNING.md are designed to exist simultaneously.
• Skill selection drives file selection: The invoked skill automatically picks its own state file and ignores the others.
• No manual merging: These files contain incompatible curriculum data; merge attempts will corrupt your progress.
• Legacy filename handling: learn‑mcp automatically migrates MCP‑ENGINEERING‑LEARNING.md to MCP‑LEARNING.md if needed.
• Targeted resets: Delete only the specific state file you wish to restart.

Frequently Asked Questions

What happens if I delete one of the state files?

Deleting a state file erases all progress for that specific skill. The next time you run that skill, it will generate a fresh state file and restart the curriculum from the beginning. Other state files remain unaffected, preserving progress on their respective tracks.

Can I merge the content of these files to consolidate my progress?

No. Each file maintains a distinct schema and lesson manifest tailored to its skill. LEARNING.md tracks the full AI engineering curriculum, while MCP‑LEARNING.md follows a 17‑lesson MCP‑specific manifest. Merging them manually will cause parsing errors when the skills attempt to read their state.

Why does learn‑mcp check for MCP‑ENGINEERING‑LEARNING.md?

This is legacy filename support. Earlier versions of the repository used MCP‑ENGINEERING‑LEARNING.md as the state filename. The current learn‑mcp skill checks for this legacy file and automatically renames it to MCP‑LEARNING.md (as shown in skills/learn‑mcp/SKILL.md lines 82‑86) to ensure backward compatibility without duplicating progress data.

Do I need to manually specify which state file to use?

No. The curriculum engine handles this automatically. Simply invoke the skill you want to work with (learn, learn‑mcp, or learn‑agent‑skills), and it will locate and update only its designated state file. Manual specification is unnecessary and could lead to configuration errors.

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