Help us improve
Share bugs, ideas, or general feedback.
From alemtuzlak-skills
Generates structured markdown courses with interactive HTML mini-courses for any topic, using evidence-based learning techniques.
npx claudepluginhub alemtuzlak/skills --plugin self-improveHow this skill is triggered — by the user, by Claude, or both
Slash command
/alemtuzlak-skills:teach-meThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produce a self-paced markdown course + self-contained HTML mini-course for any topic the user wants to learn. Designed for adult learners (CEFR B1 reading level, no prior knowledge), grounded in cognitive psychology and instructional-design research.
Generates researched, module-based learning plans for technical or general topics. Saves plans and quiz progress to ~/.claude/learning/ directories. Resumes existing plans with status.
Turns the workspace into a stateful teaching environment with a mission, glossary, learning records, and progression tracking.
Delivers structured multi-session tutoring for technical topics with Socratic diagnostics, knowledge graphs for prerequisites, agendas, teaching, quizzes, and progress tracking.
Share bugs, ideas, or general feedback.
Produce a self-paced markdown course + self-contained HTML mini-course for any topic the user wants to learn. Designed for adult learners (CEFR B1 reading level, no prior knowledge), grounded in cognitive psychology and instructional-design research.
/teach-me <topic> (or no arg — ask for the topic)context7 instead)This skill is grounded in well-replicated learning science. The rules below are not negotiable defaults — they are what the user is paying for:
<div class="state-sequence"> instead. Same shape in every panel, delta annotated, caption = trigger + invariant. The reader sees the evolution; they don't read a story about it.Debunked — never use: learning styles (VAK), 10,000-hours framing, gamification streaks/badges, decorative imagery for "engagement", "right-brain/left-brain", "digital natives".
digraph teach_me {
rankdir=TB;
"Parse invocation" [shape=box];
"Existing folder?" [shape=diamond];
"Output location" [shape=box];
"Pre-interview" [shape=box];
"Research (4 parallel agents)" [shape=box];
"Synthesize + write OUTLINE.md" [shape=box];
"User picks chapters" [shape=box];
"Write WRITING_GUIDE.md" [shape=box];
"Chapter generation (parallel batches)" [shape=box];
"Consistency pass" [shape=box];
"Build index.html" [shape=box];
"Open folder + browser" [shape=doublecircle];
"Parse invocation" -> "Existing folder?";
"Existing folder?" -> "Output location" [label="no"];
"Existing folder?" -> "Output location" [label="extend / fresh / cancel"];
"Output location" -> "Pre-interview";
"Pre-interview" -> "Research (4 parallel agents)";
"Research (4 parallel agents)" -> "Synthesize + write OUTLINE.md";
"Synthesize + write OUTLINE.md" -> "User picks chapters";
"User picks chapters" -> "Write WRITING_GUIDE.md";
"Write WRITING_GUIDE.md" -> "Chapter generation (parallel batches)";
"Chapter generation (parallel batches)" -> "Consistency pass";
"Consistency pass" -> "Build index.html";
"Build index.html" -> "Open folder + browser";
}
Do not skip phases. Track progress with TaskCreate so the user sees where you are.
programming, science, everything) — ask the user to narrow with 2–3 concrete examples: "That's very broad. Want to narrow to something like 'asynchronous programming patterns in TypeScript' or 'how compilers work'?" Wait for a narrower answer.AI, databases) — proceed; the freeform scope question in the interview will narrow it further.-, collapse repeated -, trim. Example: Asynchronous Programming → asynchronous-programming.<output-location>/learn-<slug>/ already exists.AskUserQuestion:
learn-<slug>-archived-YYYY-MM-DD/ and proceed with a new course.teach-me-output-location or similar. Use Glob on C:/Users/AlemTuzlak/.claude/projects/F--projects/memory/*.md and Grep for teach-me.<path>."AskUserQuestion:
F:/projects/learning/ (creates the folder if missing) — Recommended../)./teach-me runs?" — yes/no via AskUserQuestion.teach_me_output_location.md with frontmatter type: user and the path in the body. Update MEMORY.md with one line.Ask in two round-trips:
Q1 [Current knowledge]: How much do you already know about <topic>?
- Never heard of it
- Know the terminology, no hands-on experience
- Have built basic things
- Intermediate practitioner
Q2 [End-goal proficiency]: Where do you want to end up?
- Conceptual overview only
- Can build basic things
- Can build production-grade things
- Can teach others
Q3 [Depth budget]: How much do you want?
- Quick primer (~3–5 chapters)
- Standard (~6–10 chapters)
- Deep dive (everything researched, 10–15+ chapters)
Q4 [Practice load]: How much hands-on practice?
- Light (read-focused)
- Standard (read + retrieval + occasional exercise)
- Heavy (every chapter has worked examples and exercises)
Send this exact message (substitute <topic>):
Two more things before I start researching:
1. What do you already know well? List languages, frameworks, fields, hobbies — anything you've spent serious time on (e.g. "TypeScript, React, music theory, cooking, chess"). I'll use these as analogy sources to anchor new concepts to what you already know.
2. Any specific angle within , or should I cover it broadly? Say "surprise me" for full coverage.
Wait for a single reply containing both. Parse loosely — accept comma-separated lists, bulleted lists, or freeform.
Persist the answers in a working struct (you'll write them into OUTLINE.md and WRITING_GUIDE.md later).
Dispatch one batched Agent call containing 4 general-purpose subagents. They run in parallel. Each gets a self-contained brief and reports back a structured report.
Lane A — Authoritative content. Find top articles, tutorials, conference talks, and papers on <topic>. WebSearch + WebFetch the highest-signal results. Return 8–15 with one-line "why-to-read" for each, tagged [article|tutorial|talk|paper].
Lane B — Niche influencers and practitioners. Find specific people known for <topic> — not tech celebrities, but practitioners with their own blogs/newsletters/Twitter who go deep on this niche. Return 4–8 with: name, personal outlet (blog URL), signature post URL, one-line on why they're worth following. Skip anyone whose only output is corporate marketing.
Lane C — Canonical references. Official docs, specs, reference implementations, definitive textbooks. If <topic> is a library/framework/CLI tool, use the context7 MCP (resolve-library-id then query-docs) to get current canonical docs. Return 3–8 sources with version info.
Lane D — Subtopic landscape and canonical language. Survey the topic to produce a tree of subtopics with one-line descriptions (typically 8–15 subtopics). Suggest an instructional ordering (prerequisites first, advanced last). If the topic is technical, determine the canonical language used by official docs / most common in production (e.g. Temporal → TypeScript or Go; LangGraph → Python). State explicitly: "Canonical language: X, because Y."
Each agent reports under 800 words, structured. After all 4 return, synthesize.
<output-location>/learn-<slug>/OUTLINE.md with this structure:# Learning <Topic>
## Your goal (recorded)
- **Current level**: <answer from Q1>
- **Target proficiency**: <answer from Q2>
- **Depth**: <answer from Q3>
- **Practice load**: <answer from Q4>
- **Known domains (analogy bank)**: <comma-separated from Round 2>
- **Scope/angle**: <answer from Round 2>
## Subtopic landscape (from research)
1. <subtopic 1> — <one-line description>
2. <subtopic 2> — <one-line description>
...
## Suggested ordering
A prerequisite-respecting order with rationale for each step.
## Recommended chapters (~N, based on your depth budget)
Numbered list of proposed chapters. Each entry: short title + 1 line on what's covered + estimated cards (5–9 per chapter).
## Canonical language (technical topics only)
<language and one-line justification>
## Recommended sources
- [Source 1](url) — [type] — why-to-read
...
## Niche influencers worth following
- **Name** — [blog url] — signature post: [post url] — one-line on why
...
Bash code --new-window "<absolute-path-to-OUTLINE.md>".I've written the outline to
<absolute-path>and opened it for you.Reply with which chapters to write:
all— write every recommended chapter1,3,5-7— specific chapters or ranges- Freeform — describe in your own words what to focus on
reshape— tell me what to add, remove, merge, or reorder before we commitIf you choose
reshape, I'll revise OUTLINE.md and ask again.
reshape, take their notes, revise OUTLINE.md, save, re-open, ask again. Loop until committed.picks = [...].Write <output-location>/learn-<slug>/WRITING_GUIDE.md. This file is the shared brief for all chapter-writer agents and the consistency-pass agent. It must be comprehensive and concrete.
Use the template at <skill-dir>/assets/templates/WRITING_GUIDE.template.md as the starting point — substitute the user's recorded interview answers into the placeholders ({{TOPIC}}, {{CURRENT_LEVEL}}, {{TARGET_PROFICIENCY}}, {{PRACTICE_LOAD}}, {{KNOWN_DOMAINS}}, {{SCOPE}}, {{CANONICAL_LANGUAGE}}).
Also point chapter writers at the component library reference at <skill-dir>/assets/COMPONENTS.md — they should skim it before writing. Callouts, diagram cards, compare blocks, tabs, stat cards, platform pills, and step lists are all available; some are auto-generated from markdown conventions, the rest are explicit HTML inside markdown.
Verify the generated file enforces all 12 pedagogy rules listed in the "Pedagogy Foundation" section at the top of this SKILL.md. If any rule isn't represented in the guide, add it before continuing.
Generate the picked chapters in parallel batches of 3–5 writer subagents per round, sequentially across rounds.
picks.Agent call containing 3–5 general-purpose subagents in parallel. Each writes exactly one chapter.WRITING_GUIDE.md (must read first)OUTLINE.md (for context on what the other chapters cover)<output-location>/learn-<slug>/NN-<chapter-slug>.md (where NN is zero-padded chapter number)<output-location>/learn-<slug>/diagrams/chNN-<name>.svgpicks are written.---
chapter: NN
title: <Chapter Title>
slug: <chapter-slug>
requires:
chapters: [NN, ...]
concepts: [concept-slug, ...]
introduces:
concepts:
- slug: concept-foo
label: Foo
first-definition: "A short canonical definition."
terms:
- term: workflow
definition: A sequence of steps that survives process restarts.
callbacks: [concept-bar, concept-baz] # concepts from earlier chapters used here
fading-stage: full-worked | backward-faded | prompt-only
---
## What you'll learn
- 3–5 bullet items
## Prereq check
> Before you start, try answering these. Click each to reveal the answer.
<details><summary>1. <prereq question 1></summary>
<answer>
</details>
<details><summary>2. <prereq question 2></summary>
<answer>
</details>
<details><summary>3. <prereq question 3></summary>
<answer>
</details>
---
## Card 1: <Card title>
<Concrete-first opener. First sentence MUST name a concrete observable instance. No abstract noun in the first sentence until a concrete instance has been introduced.>
<Body. One concept. ≤500 words for the whole card.>

*<one-sentence caption>*
<Maybe more body — kept short, supports the diagram.>
> **Self-explain**: Finish this sentence — "<concept> works because ___"
>
> <details><summary>Sample answer</summary>
> <model explanation in 1–2 sentences>
> </details>
---
## Card 2: <Card title>
(same structure)
---
<More cards. 5–9 cards total per chapter.>
---
## Recall (before scrolling away)
<details><summary>1. <free-recall question on this chapter>?</summary>
<answer>
</details>
<details><summary>2. <free-recall question on this chapter>?</summary>
<answer>
</details>
<details><summary>3. <free-recall question on this chapter>?</summary>
<answer>
</details>
<details><summary>4. Callback: <question referencing a concept from 2 chapters back, by name>?</summary>
<answer>
</details>
## Recap
- <mirror of the "What you'll learn" bullets, now stated as facts>
## Next
<one sentence pointing to the next chapter>
--- on its own line. Each card is 250–500 words..svg files in diagrams/. Caption mandatory. No decorative imagery.## Legend headers.[term](#term-slug) to a glossary entry created in an earlier chapter (check the term ledger you were given). No exceptions.— (U+2014) and en-dash – (U+2013). Restructure the sentence.x used as a multiplier in prose.**Label**: mini-headings sprayed across paragraphs. Bold is for the one term that matters, not for visual structure.0 0 800 480 (the viewer container is 800×480 max; smaller is fine)#1f2937 (text/strokes), #3b82f6 (primary fill), #f59e0b (accent), #10b981 (success/positive)system-ui, -apple-system, sans-serif, size 14–18pxdata-interactive="hover-explain" on the root <svg> and add data-explain="<text>" attrs on labeled elements. The HTML viewer wires up tooltips automatically.Dispatch one general-purpose subagent with this brief:
Read every chapter file in
<output-location>/learn-<slug>/. Validate and fix:
- Concrete-first openers — first sentence of every chapter must name a concrete instance. Patch openers that start with abstract definitions.
- Banned phrases and constructs. Scan for the banned-phrase list in WRITING_GUIDE.md. Rewrite offending sentences. This includes:
- All idioms and filler from rule 7 and rule 8.
- Every em-dash
—and en-dash–in chapter prose, captions, recall answers, and summaries. Restructure the sentence (split, comma, parentheses).- "It is not X, it is Y" / "It's not X: it's Y" / "Not just X, but Y" framing. Rewrite as a direct statement.
- "Key insight", "The key insight", "Key takeaway", "Pro tip", "Bottom line", "TL;DR" and similar insight-announcer phrases. Drop the announcer; keep the claim.
- Glyph separators like
xused as a multiplier in prose. Use the wordby.- Bolded
**Label**:mini-headings sprayed across paragraphs of a single card (more than 2 in a card). Flatten into prose.- Sentence length — flag sentences >25 words. Rewrite them.
- Card length — flag cards >600 words. Either split into two cards or compress.
- Diagram references — every
must resolve to an actual file. If a chapter references a missing SVG, write a minimal SVG intodiagrams/.- Analogy hygiene — every "Analogy:" or "is like a/think of … as" must have a "Where this breaks down:" within 2 paragraphs.
- Jargon gate — every technical term must be defined on first use or link to a glossary entry. Maintain a consolidated term ledger (see step 11).
- Spaced callbacks — each major concept introduced in chapter N must be used (not redefined) in ≥2 later chapters. Check the introduces/callbacks frontmatter. Patch chapters that fail this.
- Required sections — every chapter must have
## What you'll learn,## Prereq check, ≥3 cards,## Recall,## Recap,## Next. Add any missing sections.- Cross-references —
Chapter Nstyle references must point to chapters that exist. Patch dangling refs.- Write
README.md— TOC linking each chapter, recorded goal, suggested reading order, prerequisites summary, learning-time estimate.- Write
resources.md— only cite sources actually used in chapters. Plus the influencer block from research. Each source: title, type tag[official|blog|video|paper|community], one-line why-to-read.- Write
concepts.json— machine-readable concept ledger:[{slug, label, first-definition, introduced-in, called-back-in: []}].- Write
terms.json— machine-readable term ledger:[{term, definition, first-use-chapter}].- Write
course-meta.json—{title, slug, goal, current-level, target-proficiency, depth, practice-load, known-domains, scope, canonical-language, chapters: [{number, title, slug, file, requires, introduces}]}.
The consistency-pass agent writes the corrected files in place. Returns a summary of what was patched.
The HTML is built by a Node script in the skill's assets folder. It pre-renders code blocks with Shiki (dual github-light / github-dark themes, CSS-variable mode) so the runtime needs no highlighting library.
Acquire marked.min.js if missing (<skill-dir>/assets/marked.min.js). Use WebFetch from https://cdn.jsdelivr.net/npm/marked/marked.min.js and Write to disk. One-time cache. No highlight.min.js — Shiki replaces it.
Install Shiki if <skill-dir>/assets/node_modules/shiki/ is missing. Run:
npm --prefix <skill-dir>/assets install
This is a one-time setup; subsequent builds reuse the cached install. The package.json and package-lock.json are committed with the skill.
Run the build script:
node <skill-dir>/assets/build-html.mjs <output-location>/learn-<slug>
The script:
<skill-dir>/assets/templates/index.template.html, styles.css, viewer.js, marked.min.js.course-meta.json, concepts.json, terms.json, resources.json.codeToHtml with both light and dark themes (CSS-variable mode). Marked.js sees the resulting HTML in the markdown body and passes it through unchanged at runtime.course-meta.chapters.</script> and <!-- inside inlined markdown and JSON.{{PLACEHOLDER}} tokens in the template.index.html to the course folder.If the script fails, capture stderr and report. Common causes: missing chapter file referenced from course-meta.json, Shiki not installed (npm install step skipped), or an unfamiliar code-fence language (the script falls back to plain <pre><code> for unsupported languages — see SUPPORTED_LANGS in build-html.mjs).
The HTML viewer at runtime:
--- separators into cards.<details> elements render as click-to-reveal.terms.json).localStorage keyed by teach-me:<slug>:progress.data-theme automatically via CSS overrides.<svg data-interactive="hover-explain"> gets tooltips wired to child [data-explain] elements.Bash explorer.exe "<absolute-path-to-learn-slug-folder>"Bash start "" "<absolute-path-to-index.html>"</script> inside chapter markdown. Re-run the escape step and retry./teach-me <same-topic> invocation, the existing-folder check offers "Extend → resume".TaskCreate at the start to track phases. Mark each phase in_progress when you start it, completed when done. The user wants to see progress.WRITING_GUIDE.md template is unclear for the topic at hand (e.g. analogy bank empty because user gave no known domains), call it out in the guide and proceed without forcing analogies.