Skip to content

SKILL.md

Latest commit

 

History

History
125 lines (83 loc) · 7.98 KB

SKILL.md

File metadata and controls

125 lines (83 loc) · 7.98 KB
Raw
name code-tutorial
description Generate beginner-friendly, line-by-line code tutorials for any codebase — first a flow "main-line" doc that traces ONE user action end-to-end (file·function·line), then per-file deep-dives with inline syntax mini-lessons. Best for onboarding docs, teaching a codebase to non-experts, or explaining an unfamiliar repo. Triggers on requests like "explain this codebase line by line", "write a beginner walkthrough", "teach me how this repo works for a total beginner".

Code Tutorial Generator

Turn any codebase into a structured, beginner-friendly tutorial series. The audience is a "beginner's beginner" — someone who may not know the language's syntax yet. The output is a set of Markdown docs that teach the repo the way a patient mentor would: first the big picture, then every line.

The order matters and is the heart of this skill:

Phase 1 — build the FLOW MAIN-LINE first (one doc that follows a single user action end-to-end), then Phase 2 — write the per-file line-by-line deep-dives.

Building the main-line first gives both you and the reader a global map, so every later deep-dive has a known place in the whole. Doing it the other way around (files first) leaves the reader assembling a puzzle with no picture on the box.

When to Use

Use this skill when the user wants to teach or document a codebase for people who don't know it well, e.g.:

  • "Explain this whole repo line by line for a total beginner."
  • "Write onboarding docs that walk through how a request flows through the code."
  • "I'm new to this language — annotate the code and teach me the syntax as it appears."
  • "Produce a learning series for src/ that a non-programmer could follow."

Not for: quick one-off "what does this function do" answers (just answer directly), or API reference generation (that's a different genre).

Core Principles

These are distilled from real tutorials that worked. Hold to all of them.

  1. Audience = beginner's beginner. Assume no prior syntax knowledge. Explain with plain language and analogies before jargon. Define every term the first time it appears.
  2. Syntax mini-lessons inline. The first time any language construct appears (a keyword, an operator, a pattern), stop and teach it in a short boxed aside (a「Syntax mini-lesson」/「语法小课堂」). Never assume the reader has seen it before.
  3. Dependency order, not filename order. Read and present files so that each doc only relies on concepts already taught. Foundations (types/contracts/config) first; the files that depend on them later.
  4. Cite real locations, verified. Every file · function · line reference must be checked against the actual source before writing it. Wrong line numbers actively mislead a beginner. Re-read the file and confirm.
  5. Code is the source of truth. When code contradicts comments/docs/README (e.g. a "stub" that is actually fully implemented), say so honestly and follow the code. Teaching readers to notice this is itself a skill.
  6. Deliver in batches, pause to digest. For a large repo, hand off a few docs at a time and let the reader catch up, rather than dumping everything at once.
  7. Cross-link relentlessly. Each doc points back to where a concept was first taught and forward to what's next. Maintain a running index so nothing is orphaned.

Two-Phase Workflow

Phase 0 — Scope & plan (before writing anything)

  1. Skim the repo: entry point, main modules, dependency direction.
  2. Pick the target language(s); note the build/run model.
  3. Decide the recommended reading order (dependency order). This becomes the Phase-2 sequence.
  4. Pick the one user action to trace in Phase 1 — the most representative end-to-end path (e.g. "user sends a command → effect happens"). It should touch the spine of the system.

Phase 1 — Build the flow main-line FIRST

Write a single "journey" document that follows your chosen action from the user all the way to the final effect, one hop at a time.

For each hop, give: the file, the function/method, the exact line range, a one-line plain-language description, and a link to the Phase-2 deep-dive for that file (the deep-dive may not exist yet — link to where it will be; that's fine).

Before writing each citation, open the source and verify file:function:line. This is non-negotiable — Principle 4.

Include:

  • A "shape changes" table showing how the data is transformed at each layer (e.g. natural language → object → JSON → wire bytes → …). This is often the single most clarifying artifact.
  • A return path if the action expects a response (how the answer comes back — callbacks, id-pairing, etc.).
  • A station quick-reference table (every hop in one scannable table).
  • A short "global lessons" section naming the cross-cutting patterns (layering, adapter, id-pairing, caching…) the reader will meet again.

Use references/flow-doc-template.md as the skeleton.

Phase 2 — Per-file line-by-line deep-dives

Now walk the files in dependency order. One doc per source file. Each doc follows the same fixed structure so the reader builds a rhythm:

  1. Locator block — link to the source file + one paragraph on what this file is and why it's read at this point in the order.
  2. Line-by-line breakdown — quote real code in small chunks; explain every line; insert a「Syntax mini-lesson」the first time each construct appears.
  3. Chapter recap — what this file does, in plain language.
  4. Syntax checklist — bullet list of the new/reinforced syntax points this doc covered (a reference the reader can scan later).
  5. Next link — point to the next doc in the order.

Maintain a series index (README) with: a progress table (which files are done), and a "syntax learning map" (each syntax point → the doc where it's first taught), so a reader who forgets something can jump back.

Use references/line-by-line-template.md as the per-doc skeleton.

Diagrams (optional, via external skills)

Replace key ASCII diagrams with rendered visuals by invoking the relevant drawing skill:

  • Directed flow / call chains (the Phase-1 main-line, a switch dispatch, a data-flow) → invoke the graphviz skill (```dot fenced blocks).
  • Layered/tiered architecture (a 3-tier system, a stack of layers) → invoke the architecture skill (embedded HTML/CSS).

Pick by shape: arrows-and-nodes → graphviz; stacked colored tiers → architecture. Keep the explanatory prose; only the ASCII art becomes a rendered figure. A minimal dot flow chain:

digraph flow {
    rankdir=LR;
    node [shape=box, style="rounded,filled", fillcolor="#dbeafe"];
    user [label="user input"];
    handler [label="handler()\nfile.ts:42"];
    out [label="effect"];
    user -> handler -> out;
}

See references/diagrams.md for when-to-use guidance and more DOT snippets (cluster grouping, switch dispatch).

Quality Checks (before handing off)

  • Line numbers: spot-check several file:function:line citations against the real source.
  • Links: every relative link to another doc/source resolves.
  • Diagrams render: validate dot blocks (dot -Tsvg) or preview; architecture HTML blocks have balanced tags and no blank lines inside the structure.
  • Order holds: no doc uses a concept not yet taught.
  • Honesty: any code-vs-docs discrepancy is flagged, not papered over.

Related Files