code-tutorial

A Claude Code / Agent Skill that turns any codebase into a beginner-friendly, line-by-line tutorial series.

The audience it writes for is a "beginner's beginner" — someone who may not even know the language's syntax yet. It produces Markdown docs that teach a repo the way a patient mentor would.

The idea

Most "explain this code" output dumps file after file and leaves the reader assembling a puzzle with no picture on the box. This skill flips the order:

1. Phase 1 — Flow main-line first. One lead doc traces a single user action end-to-end (e.g. "user types a command → robot moves"), hop by hop, each tagged with file · function · line and linked to its deep-dive. This is the global map.
2. Phase 2 — Per-file deep-dives. Then it walks the files in dependency order, one doc per file, explaining every line and teaching each new syntax construct in an inline 「Syntax mini-lesson」 the first time it appears.

Building the map first means every later deep-dive has a known place in the whole.

Principles it follows

• Write for a total beginner; analogies before jargon.
• A syntax mini-lesson the first time each construct appears.
• Dependency order, not filename order.
• Verify every file:function:line against the source before writing it.
• Code is the source of truth — flag any code-vs-docs discrepancy honestly.
• Deliver in batches; maintain a running index + a "syntax learning map."

Install

Copy the code-tutorial/ folder into your skills directory:

# user-level (all projects)
cp -r code-tutorial ~/.claude/skills/code-tutorial

# or project-level
cp -r code-tutorial /path/to/your/project/.claude/skills/code-tutorial

Then invoke it by asking, e.g. "write a beginner line-by-line tutorial for this repo", or /code-tutorial.

Usage

1. Point it at a repo and name the audience/language.
2. It picks one representative action and writes the flow main-line doc first.
3. It then generates per-file deep-dives in dependency order, in batches, with a series index.

See examples/rosclaw-excerpt.md for what finished output looks like, and the templates in references/.

Optional dependency — diagrams

To render the diagrams (flow charts, dispatch graphs, layered-architecture figures) instead of ASCII art, this skill invokes two external drawing skills:

• graphviz — for flow / call-chain / dispatch diagrams (```dot blocks)
• architecture — for layered/tiered architecture figures (embedded HTML)

Install them from:

https://github.com/markdown-viewer/skills

The tutorial generation works without them (it falls back to ASCII/text); they just make the key diagrams look better.

Layout

code-tutorial/
├── SKILL.md                        # the skill: principles + two-phase workflow
├── references/
│   ├── flow-doc-template.md        # Phase 1: flow main-line skeleton
│   ├── line-by-line-template.md    # Phase 2: per-file deep-dive skeleton
│   └── diagrams.md                 # when to use graphviz vs architecture + DOT snippets
├── examples/
│   └── rosclaw-excerpt.md          # real finished-output excerpt
├── README.md
└── LICENSE

Credits

Distilled from a real RosClaw tutorial series (https://github.com/PlaiPin/rosclaw, under learn/). Diagram skills by markdown-viewer/skills.

License

MIT — see LICENSE.