/learn — Socratic Tutor for Vibe Coders

A Claude Code skill that teaches through Socratic dialogue, not lectures. Built for anyone who works with AI and wants to understand what they built — whether that’s code, configurations, workflows, or structured data.

The Problem

Everyone is vibe coding. AI writes the code, you ship the app. But when something breaks, you’re stuck. You don’t know what an API route does, why await matters, or what happens when your fetch call fails.

And it’s not just code. PMs use AI to generate configs they don’t understand. Designers prototype with frameworks they can’t debug. Researchers build automation pipelines that are black boxes. The pattern is the same: AI does the work, you lose control.

This skill fixes that. It teaches you the foundations by asking questions about your own work — not by lecturing.

What it does

• Socratic method: Never explains first. Asks what you think, builds on your answer, follows your curiosity
• 5-level hint ladder: Starts with open questions, only gives answers as a last resort — and always ends with a follow-up question
• Context cascade: Adapts to whatever you’re working with — git diffs, codebases, config files, markdown docs, or just a conversation. Never dead-ends.
• Adapts to you: Learns your background (design, PM, data, research) and tailors analogies to your world
• Frustration-aware: Detects when you’re stuck and changes approach instead of pushing harder
• Teach mode: When you’re confident, flip the roles — you teach, the skill plays dumb and asks naive questions
• Progress tracking — two files: a JSON brain for the skill (confidence, spaced repetition, open threads) AND a markdown journal in your voice (first-person, organized by thematic eras). The JSON tells the skill what to teach next; the journal tells you where you came from.
• Delight: Celebrates real growth moments, remembers your journey across sessions

Install

git clone https://github.com/deniz-miro/claude-learn-skill.git
cp -r claude-learn-skill/learn ~/.claude/skills/learn

That’s it. The skill is now available as /learn in any Claude Code session.

Where your progress lives

By default, ~/.claude/learning-progress.json. One file, persists across every project and every session on your machine. Switching repos, cloning a fresh checkout, or migrating a codebase doesn’t reset your progress — because the file lives next to your Claude config, not inside any single project.

Override: set $LEARN_PROGRESS_PATH to point elsewhere if you want a custom location (e.g. a synced cloud folder, or a sandbox-wide path that spans multiple project directories).