Executable Claude Code Learning Path

This dependency-free prototype turns the existing seven-module learning path into a local progression. It stores only learner-owned state in .claude/learning/claude-code-guide-progress.json under the target project.

What it does

• creates one of four tracks: Beginner, Practitioner, Production, or Maintainer;
• unlocks modules only after their prerequisites have recorded evidence;
• requires a non-empty evidence note for every completion;
• produces a deterministic next module, current status, and due-review list;
• schedules reviews at 1, 3, 7, 14, 30, 60, and 90 days;
• writes the JSON state atomically and refuses corrupt state.

It is a local learning aid. It does not prove competence, upload evidence, or replace a human review of an exercise.

Quick start

Use the public self-assessment workflow first:

/self-assessment quick

Then start the lowest track matching your immediate goal:

python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" init --track Beginner
python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" next

After performing the exercise, record the evidence:

python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" complete module-01 \
  --evidence "Installed Claude Code, ran /help, and recorded the version."
python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" status
python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" due

The skill works from a third-party project because it addresses its installed script through CLAUDE_SKILL_DIR and writes state under the current directory. For example:

cd /path/to/project
python3 "${CLAUDE_SKILL_DIR}/scripts/progress.py" --root "$PWD" init --track Practitioner

Tracks

Track	Intended result	Required modules
Beginner	Work safely through a first Claude Code workflow	01, 02, 03
Practitioner	Build reusable local agent and skill workflows	01 to 05
Production	Add hooks, verification, and advanced coordination	01 to 07
Maintainer	Maintain shared practices and operational safeguards	01 to 07

The diagnostic helps select a starting track, but it does not remove prerequisite checks. A learner who selects Production still completes the sequence in order.

Self-assessment mapping

Self-assessment result	Select this track
Beginner	Beginner
Intermediate	Practitioner
Advanced	Production

Maintainer is a manual choice, not a self-assessment result. Use it only when the goal includes shared governance, such as maintaining team instructions, controls, or evidence practices.

Module map

Module	Guide page	Required exercise
01	Installation and setup	View available commands
02	Core loop	Complete loop
03	Memory and configuration	Create your CLAUDE.md
04	Agents and specialization	Create a test-writer agent
05	Skills and automation	Create a domain skill
06	Hooks and events	Create a validation hook
07	Advanced patterns	Build a multi-agent workflow

The canonical machine-readable map is assets/path.yaml. It uses JSON syntax, which is valid YAML, so the standard-library-only Python tool can parse it without PyYAML.

State and recovery

The state file contains only the selected track, module completion dates, and evidence notes. init will not overwrite it. Every save writes a complete temporary file in the same directory, flushes it, and atomically replaces the old file.

If status, next, complete, or due reports corrupt state, stop. Preserve a copy of .claude/learning/claude-code-guide-progress.json for inspection, repair it manually only after identifying the cause, or remove it deliberately and start a new profile. The prototype will not guess how to recover learner evidence.

Tests

python3 -m unittest -v examples/skills/learning-path/tests/test_progress.py

The focused suite covers profile creation, atomic persistence, prerequisite enforcement, evidence gates, next-module selection, review intervals, and corrupt-state failure.

Skill validation boundary

path.yaml is valid JSON and therefore valid YAML. The dependency-free runtime validates this exact JSON subset with the Python standard library. The bundled quick_validate.py skill validator requires PyYAML because it imports yaml before it parses SKILL.md frontmatter. If PyYAML is absent, frontmatter validation is UNKNOWN. Do not report it as a passed skill validation. The local unit suite still verifies that the runtime can load the shipped path definition.