How to Quickly Learn and Master AI‑Generated Projects with the /teach Skill

Problem

AI can generate high‑quality code quickly, but developers become the bottleneck because they must spend a long time understanding that code. The traditional clone‑and‑browse‑many‑files workflow with hand‑drawn sketches is wasteful in the AI era.

Solution Overview

Three composable skills are introduced and demonstrated on a real workspace called zero-learn, built from the open‑source project github.com/Gitlawb/zero: /teach – converts a codebase into a reusable, stateful teaching course. /insight-diagram – automatically creates UML, architecture, sequence, and flow diagrams. /architecture-diagram – renders those diagrams into professional, self‑contained HTML+SVG.

/teach Skill

It is a stateful, multi‑session request that creates a teaching workspace consisting of six file types, each with a clear purpose: MISSION.md – defines why you learn, what success looks like, and the scope. RESOURCES.md – lists trusted knowledge sources. NOTES.md – records learner profile and teaching preferences. learning-records/ – stores verified key understandings (ADR‑style). lessons/ – one HTML lesson per topic, the main teaching product. reference/ – reusable quick‑reference docs.

The skill enforces “desirable difficulty”: lessons are short, single‑topic, include retrieval‑practice quizzes, and are interleaved with spacing to boost long‑term storage strength. It refuses to start without a clear mission and actively asks the user to clarify the learning goal.

/insight-diagram Skill

This skill analyzes any codebase, extracts component lists, call graphs, core types, and deployment topology, then asks the user which of 17 diagram types to generate. The default recommendation is a trio—architecture diagram, sequence diagram, and flowchart.

Four‑step workflow:

Analyze the repository (read CLAUDE.md if present, scan source tree, identify entry points, interfaces, and dependencies).

Prompt the user to select desired diagrams.

For each diagram, first read a high‑quality example from examples/ (13 templates) to copy layout, node style, and annotation style, then replace the placeholder business data with the target project’s real architecture.

Report generated files and brief descriptions.

Hard rules prevent AI slop: no overlapping nodes, arrow‑z‑order (draw arrows before nodes), mandatory spacing, mask layers, and legend placement outside all bounding boxes.

/architecture-diagram Skill

This rendering engine turns a diagram description into a single HTML file containing embedded CSS, inline SVG, and no JavaScript. It uses a dark design system (slate‑950 background, JetBrains Mono font) with a semantic colour palette (frontend cyan, backend green, database purple, cloud amber, security red, bus orange, external gray). Layout hierarchy: title → rounded‑corner card with the SVG → three summary cards at the bottom → footer metadata.

Rendering rules include arrow‑z‑order, transparent masks beneath arrows, minimum vertical spacing of 40 px, and placing the legend outside the diagram bounds.

Zero‑learn Workspace Example

The zero-learn workspace contains 20 lessons that dissect the Zero coding agent. Lessons are grouped into six modules covering core loop, interaction & persistence, provider & streams, sandbox security, session topology, and tool system. Each lesson focuses on a single architectural decision and cites exact file:line locations, ensuring precise mapping to the source.

All lessons are self‑contained HTML files that share assets/course.css for uniform styling and assets/quiz.js for retrieval‑practice quizzes. The root index.html lists all lessons with hook sentences and can be served directly via GitHub Pages, keeping the learning notes outside the original repository ( ../zero/… paths).

When to Use Which Skill

Use /understand-anything or /code-to-spec for machine‑focused tasks. Use /insight-diagram + /architecture-diagram for visualisation that anyone can consume. Use /teach when the output must be retained by a human, because it optimises storage strength rather than mere fluency.

Key Technical Takeaways

Reading code is not the same as learning it; /teach adds retrieval practice, interleaving, and spacing to improve long‑term retention.

The six‑file workspace of /teach organises purpose, resources, learner profile, ADR‑style records, and lessons with exact source references. /insight-diagram decides which diagrams to create and follows a “read example first” rule to combat AI slop. /architecture-diagram provides a consistent dark‑theme rendering engine with strict layout rules.

The three skills are composable: analysis → diagram selection → rendering, or teaching → deep understanding, illustrating that effective AI capability is a set of modular, combinable skills rather than a monolithic prompt.