Turn AI Into Your Personal Tutor with /teach: A Complete Guide to Stateful Skill Design

When AI Does More Than Write Code — It Teaches

A developer with ten years of teaching experience — six years as a vocal coach plus four years training developers — recently condensed everything he knows about teaching into a single AI Skill during a long bus ride to London: /teach. The goal of this Skill is as simple as it is ambitious: enable anyone to learn anything.

He used this Skill to learn how to solve a Rubik's Cube — something he'd always wanted to do but never actually got around to. The entire experience, in his own words, "felt like having a real teacher by my side, teaching me the way I like to learn, perfectly matched to my pace."

This isn't a simple Q&A chatbot — it's a carefully designed, stateful teaching system. Let's break down its design philosophy and engineering implementation.

Stateful vs. Stateless: The Core Decision in Skill Design

When building an AI Skill, the first and most critical design decision is: Should this Skill be stateful or stateless?

The roots of this question trace back to fundamental principles of distributed systems design. In web development, the HTTP protocol itself is stateless — each request exists independently, and the server retains no historical information about the client. To achieve stateful behavior, developers need to introduce mechanisms like Sessions, Cookies, and databases to persist user context. In AI Agent design, this choice is equally critical: a stateless Agent starts from scratch with every conversation, making it suitable for one-off tasks; a stateful Agent requires a persistence layer to store conversation history, user preferences, and task progress, which introduces greater engineering complexity but also makes long-term interaction and personalization possible.

Stateless Skills retain no memory from previous runs. Every invocation is a fresh start, saving nothing to the file system. For example, the author's earlier grill me skill simply grills you on a topic until you're ready to start implementing. Simple, direct, one-and-done.

Stateful Skills are entirely different. They save information to the local file system or an MCP server, take notes, track progress, and can pick up right where you left off. MCP (Model Context Protocol) mentioned here is an open protocol introduced by Anthropic, designed to standardize how AI models connect with external tools and data sources — think of it as the USB port of the AI world, enabling AI to access file systems, databases, APIs, and other external resources in a unified way. In /teach, this capability transforms AI from a pure conversationalist into an agent that can operate in real environments. For instance, grill with dogs saves ADR (Architecture Decision Records) files locally, improving over time. ADRs are a lightweight documentation practice in software engineering where each record captures the context, content, and trade-off reasoning behind an important architectural decision, providing AI with critical context for understanding a project's evolutionary history.

The author initially envisioned /teach as stateless — you say "teach me this thing," it finds resources and outputs teaching content. But he quickly realized: all truly effective teaching is stateful. As a teacher, you need to remember where the student left off, have previously accumulated teaching materials on hand, and tailor the next step based on the student's progress.

These two modes aren't about better or worse — they're suited for different scenarios. But for the task of teaching, statefulness is a must.

The /teach Workflow: From Mission to Curriculum

After installing /teach, you enter an empty directory, type something like "teach me how to solve a Rubik's Cube," and the entire teaching system kicks into gear. The workflow is divided into several carefully designed stages:

Establishing a Mission Statement

This is the author's core insight as a seasoned educator — to teach effectively, you must first understand why the student wants to learn this thing. The Skill automatically creates a mission statement, such as: "Want to be able to scramble a standard 3×3 Rubik's Cube and complete at least one full solve without any help. The goal is the achievement itself, not speed, and not theory."

This "working backward from the goal" design philosophy is known in education as "Backward Design," systematically articulated by Grant Wiggins and Jay McTighe in their book Understanding by Design. The core idea: first determine the desired learning outcomes, then design assessments, and only then plan instructional activities. This stands in stark contrast to the traditional approach of "teach the content first and see what sticks."

Searching for Primary Sources

The Skill searches the web for genuine primary sources and high-credibility materials to generate course content. These resources are continuously updated as learning progresses.

Generating Interactive Lessons

All lessons are stored in a Lessons folder, numbered sequentially. A key design decision: lessons are standalone HTML files rather than Markdown. This choice reflects an important engineering trade-off — while Markdown is lightweight and readable, its expressiveness is limited; it's essentially syntactic sugar for plain text and cannot natively support interactive elements, animations, conditional rendering, or complex layouts. HTML combined with CSS and JavaScript can create full web-application-level experiences: collapsible content sections, stateful quiz components, SVG animated diagrams, and even embedded 3D model viewers. This means AI-generated lessons are essentially micro web applications that run directly in the browser with no additional toolchain required.

For example, Lesson 1, "Anatomy, Notation, and the White Cross," includes diagrams, concise explanations, key tips, and quizzes. The author even discovered that the AI generated interactive tabs — students can practice and explore directly in the browser, fully leveraging the browser's capabilities.

Zone of Proximal Development: The Soul of the Teaching Design

The entire /teach Skill's pedagogical philosophy revolves around one core concept: the Zone of Proximal Development (ZPD).

This is a classic theory in educational psychology, proposed by Soviet psychologist Lev Vygotsky in the 1930s and one of the core concepts of constructivist educational theory. Vygotsky argued that a learner's cognitive development exists across three zones: the zone of what they've already mastered (independent performance zone), the zone of what they cannot understand at all (frustration zone), and the zone in between — what they can achieve with appropriate guidance (ZPD). The companion concept is "Scaffolding" — teachers provide temporary support to help students cross the ZPD, gradually removing that support as the student's abilities grow. This theory fundamentally explains why one-on-one tutoring is far more effective than large-class instruction — because the teacher can precisely identify each student's ZPD boundaries and adjust teaching pace and difficulty accordingly.

Teaching should always take place within the zone where students are "sufficiently challenged but not overwhelmed." Every lesson must be concise and compact, landing precisely in this range — students are neither bored nor intimidated.

This plays out vividly in actual use. When the author told the AI, "I can mostly solve the Cube now, except I haven't fully memorized the step for the corner cycling," the AI would:

1. Check the state of the teaching workspace and all learning records
2. Diagnose that "the corner cycling concept is understood, but muscle memory hasn't formed yet"
3. Break the algorithm into smaller chunks and generate a focused practice lesson
4. Provide a new mental model, a four-part mnemonic, and a repetitive practice plan

This process perfectly replicates the scaffolding mechanism from Vygotsky's theory: the AI identifies the student's current ZPD boundary (conceptual understanding is in place, but procedural memory hasn't formed), then provides just the right amount of support (mnemonics, chunked practice) to help the student bridge that specific cognitive gap.

The Supporting System: More Than Just Lessons

Beyond the core curriculum, /teach automatically generates a suite of supporting files that form a complete learning support system:

• Glossary: Collects specialized terms encountered during learning, such as solving methods, grip techniques, and algorithms. Like API documentation when learning a programming language, subsequent lessons can reference these directly, keeping content more concise.
• Cheat Sheet: For example, a Rubik's Cube solution card — not a full tutorial, but a quick-reference point.
• Learning Log: When you report your progress, the AI generates records based on it, continuously tracking your learning journey.
• Notes.md: The AI's own internal notes, recording your preferences and things to watch out for.
• Community Recommendations: Lessons attempt to find relevant communities at the bottom, because "the only way to truly master something is to cultivate wisdom, and the key is genuinely engaging with a community."

The design of this supporting system aligns with the cognitive science principles of "Spaced Repetition" and "Retrieval Practice." The glossary and cheat sheet reduce cognitive load, allowing students to focus their limited working memory on new concepts; the learning log provides the data foundation for the AI to implement spaced repetition strategies — it can determine which knowledge points need review and when review would be most effective.

Because everything is saved to the file system, even if you clear the conversation context, the next time you run /teach, the AI still has all the context it needs, keeping you consistently within your Zone of Proximal Development.

From Teaching to Onboarding: Application Potential in Engineering Scenarios

From an engineering perspective, /teach has enormous potential in new member onboarding scenarios.

Traditional onboarding documentation has two pain points: first, it requires continuous maintenance to stay current; second, the content likely falls outside the new hire's Zone of Proximal Development. New hires come from vastly different backgrounds — some have used your tech stack and only need to understand the specific business domain, while others might not even know what TypeScript is.

This problem is particularly acute in software engineering. Research shows that new developers in large codebases take an average of 3-6 months to reach full productivity, and the senior engineer mentoring time they consume during this period represents a massive hidden cost. The traditional solution — writing more documentation — often falls into the "curse of knowledge" trap: document authors are so familiar with the system that they can't accurately gauge a newcomer's cognitive starting point, resulting in documentation that's either too shallow or too deep.

With /teach, you can have new hires start in their own workspace, point them at the codebase, and the AI will tailor a learning path to their actual skill level. They'll independently learn how to navigate the code and understand concepts, and you'll "have a productive employee in record time."

Developers Are the Pioneers of the AI Era

The author shared a broader reflection at the end: developers are the first group to truly experience what AI can do in a domain they're expert in. AI is currently better at writing code than almost anything else, and developers happen to be the first group that can test AI on problems they're deeply skilled at.

This "pioneer" status has historical precedent. Just as web developers in the 1990s were the first to explore patterns of digital collaboration (version control, open-source communities, agile methodologies), today's developers are the first to define workflows and best practices for human-AI collaboration. From Prompt Engineering to Agent design, from AI-assisted coding to AI-driven teaching — once these patterns are validated and refined within the developer community, they have the potential to spread to healthcare, law, finance, and every other knowledge work domain.

This means developers are the pioneers of this new frontier. The ideas we form here — Skills like /teach — can be adapted and extended to domains far beyond coding. No matter how the future of work evolves, the ability to collaborate with AI will be an extraordinarily valuable skill, and we are the first people truly beginning to do so.

/teach isn't designed to make you forever dependent on AI for learning everything. Its design philosophy is: truly hand the skill over to you, give you the confidence to go out and engage with the community, and then send you off into the wider world. That is the ultimate vision for tools like this.