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

> Resolve state file conflicts with LEARNING.md, MCP-LEARNING.md, and AGENT-SKILLS-LEARNING.md by invoking specific learn commands to ensure correct file selection and prevent overwrites.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn/SKILL.md) (lines 54‑59), the `learn` skill strictly operates on [`LEARNING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```python
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:

```bash

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.