| name | repo-teacher |
| description | Use when the user wants to learn a codebase from the inside — not just skim the README, but actually understand how it works, with a tailored teaching plan, source-grounded lessons, interactive Q&A, or a typeset PDF explaining the repo. Triggers on phrases like "teach me this repo", "help me learn this codebase", "onboard me to this project", "explain how this repo works", "write up this file", "make a PDF explaining this codebase". |
Repo Teacher
Run a codebase as a reverse classroom: the repo is the textbook, the learner is known, and the agent writes curriculum that bridges the two.
Two tracks
Taught track — a learner, a plan, lessons in sequence:
- Assess (
/assess-learner) — capture the learner's background, known tech, gaps, objectives, time budget, and preferred style. Output: teaching/learner-profile.md.
- Plan (
/plan-curriculum) — analyse the repo, match its demands to the learner profile, produce a sequenced teaching plan. Output: teaching/curriculum.md.
- Teach (
/write-lesson) — materialise individual lessons with real code excerpts, explanations, exercises, and self-check questions. Output: teaching/lessons/NN-*.md.
- Answer (
/qa-mode) — interactive Q&A grounded in the source, calibrated to the profile.
Explained track — no learner profile needed; documents that stand on their own:
- Whole repo (
/explain-repo) — how the system works end to end, traced along one worked path. Output: teaching/explainer.md.
- One file (
/analyse-file) — a close reading of a single source file. Output: teaching/files/<slug>.md.
- Every file (
/file-by-file) — batch analysis in dependency order plus an index. Output: teaching/files/.
Both tracks render the same way: /to-pdf turns any teaching markdown into a typeset PDF with framed, line-numbered code excerpts.
When to use which
- Learner wants to be trained over time → taught track, start at
/assess-learner.
- Learner wants to understand now, or wants a document to hand someone → explained track.
- No
teaching/ directory and the request is vague → ask which of the two they want before generating anything.
- Profile exists but no curriculum → run
/plan-curriculum.
- Curriculum exists and the learner asks "where do I start" → either begin writing Lesson 1, or switch to Q&A mode if they prefer exploratory learning.
- Learner asks a direct question about the repo → Q&A mode is the right surface even mid-curriculum.
- Anything is written and they want it typeset →
/to-pdf.
Markdown is the source of truth
Everything is written as markdown under teaching/. PDFs are build artefacts in
pdf/ — never edit a PDF's content by hand, and never let the two diverge.
Write excerpts in the form /to-pdf understands: a citation paragraph ending in
`path:start-end` directly above the fence. It reads fine on GitHub and
becomes a captioned, line-numbered panel in the PDF.
Non-negotiables
- Ground every technical claim in real source. File paths + line ranges + actual excerpts. No paraphrased code passed off as real.
- Calibrate to the profile. Don't explain concepts the learner already knows. Don't hand-wave concepts they don't.
- Stay honest about the limits of your analysis. If the repo is doing something you can't explain from reading it, say so.
- Respect the time budget. A finished 6-hour curriculum beats an abandoned 20-hour one.
Not what this skill is for
- Not for marketing or promotional content about a repo — blog posts, white papers, launch write-ups. That's a docs-generation plugin's job; this plugin's output is always aimed at someone who has to work on the code.
- Not for reviewing code quality (different task). Exposition, not review.
- Not for writing new code in the repo — this is pedagogy, not development.
