{
  "markdown": "# Lesson Builder — Claude Code Skill\n\nGenerate complete, standalone bilingual courses from a single prompt. Lessons, exams, flashcards, conversations, pronunciation drills, worksheets, and syllabi — any language pair, any topic, zero dependencies.\n\n## Install\n\nAdd the marketplace and install:\n\n```\n/plugin marketplace add ddtraveller/lesson-builder\n/plugin install lesson-builder\n```\n\nOr copy directly into your skills directory:\n\n```bash\ngit clone https://github.com/ddtraveller/lesson-builder.git\ncp -r lesson-builder/skills/lesson-builder ~/.claude/skills/\n```\n\n## Usage\n\n```\n/lesson-builder\n```\n\nThe skill walks you through setup interactively — or reads from a JSON config file for repeatable builds.\n\n## Quickstart — Build a Real Course from One Prompt\n\nLesson Builder is designed to take a single high-level prompt and walk it through the full **buddy workflow** (`spec → plan → tasks → implement`) to produce a complete, research-grounded course. Here's a real worked example showing the full flow.\n\n### 1. Give it a one-line brief\n\nYou start in Claude Code with a natural-language request:\n\n```\nRun lesson-builder and generate a TEFL course for Thai learners\nof English, ages 13-14. Use HeyGen for avatar videos, FLUX for\nimages, and the NVIDIA NIM model from krueng.ai/tefl/avatar_chatbot.html\nfor the live conversation chatbot. Make it research-driven and\nbreak from the conventions of existing children's courses.\n```\n\nThat's the entire input. The skill takes it from there.\n\n### 2. Step 0: automatic auth checks (parallel)\n\nBefore asking any questions, the skill checks every optional service in parallel and reports a status box:\n\n```\nService Status:\n- NotebookLM:      Ready (or: Unavailable — using web search)\n- Tavily Research: Ready (or: Unavailable — falling back)\n- Replicate:       Ready (or: Unavailable — skipping image generation)\n```\n\nIf a credential is missing, the skill tries to pull it from your secrets manager\n(AWS SSM Parameter Store by default — see [Optional Integrations](#optional-secrets-manager-auto-login) below).\n\n### 3. Discovery in parallel\n\nThe skill fetches any reference URLs you mentioned (here, the avatar chatbot page to extract the exact NVIDIA model ID and Lambda endpoint), then runs **2–3 Tavily Research calls** to gather peer-reviewed evidence on the course topic. For the example above, it ran:\n\n```bash\nPYTHONIOENCODING=utf-8 tvly research \\\n  \"evidence-based best practices teaching English ESL EFL teenagers \\\n   ages 13-14 CEFR A2 B1 2024 2025 research pedagogy\" \\\n  --model pro --json -o specs/.../tavily/teen_pedagogy.json\n\nPYTHONIOENCODING=utf-8 tvly research \\\n  \"Thai students learning English L1 interference pronunciation \\\n   grammar errors common mistakes teen learners CEFR A2 B1\" \\\n  --model pro --json -o specs/.../tavily/thai_l1_interference.json\n\nPYTHONIOENCODING=utf-8 tvly research \\\n  \"AI avatar chatbot conversational practice teen ESL motivation \\\n   engagement gamification 2024 effectiveness research\" \\\n  --model pro --json -o specs/.../tavily/tech_engagement.json\n```\n\nIn this run that produced **~71k chars of synthesized markdown across 94 cited sources** from Cambridge RECALL, MDPI, NCBI/PMC, ScienceDirect, Springer, and Thai university theses — the actual evidence base every later phase will cite.\n\n### 4. Phase 1 — `/buddy:spec`\n\nThe skill synthesizes the discovery findings into a comprehensive natural-language brief and invokes the `buddy:spec` agent. The brief is **self-contained** because the spec-writer subagent runs in a fresh context — it includes course identity, page-type designs, AI service integration details, the exact Lambda endpoint and model ID, the 12 unit topics, the pedagogical principles to bake in (with research citations), the L1 interference targets to address, and the exact output path for `spec.md`.\n\nYou can also invoke `/buddy:spec` manually from your own brief if you want full control over the wording.\n\nThe agent reads the Tavily research files, writes `specs/{YYYYMMDD}-{course_id}/spec.md`, and pauses for your review. The skill **does not proceed until you confirm**.\n\n### 5. Phase 2 — `/buddy:plan`\n\nAfter you approve the spec, the skill invokes `buddy:plan` to produce `plan.md`. This phase also runs the **Tavily → NotebookLM bridge** (if both are authenticated): the cited Tavily reports become NotebookLM URL sources, and the synthesized markdown becomes a text source. The existing `notebooklm ask` loop then runs against the enriched corpus to generate per-unit content outlines grounded in the same sources.\n\nIf NotebookLM isn't available, the skill falls back gracefully to Tavily-standalone mode and writes the plan from the research files directly.\n\n### 6. Phase 3 — `/buddy:tasks`\n\n`buddy:tasks` produces `tasks.md` — the ordered T001–T0NN work breakdown. The skill enforces the **Unit 1 verification gate**: T005 generates Unit 1 only, T006 is a browser-verify checkpoint, and bulk generation (T007) only proceeds after Unit 1 has been confirmed working. This is the load-bearing rule that keeps generation reliable.\n\n### 7. Phase 4 — `/buddy:implement`\n\n`buddy:implement` executes the tasks in order: writes the Python generator script, runs it on Unit 1, pauses for your browser verification, then bulk-generates the remaining 11 units. Hero images go through Replicate (FLUX Dev). Avatar videos go through HeyGen. Each new chatbot page is wired to the verified NVIDIA NIM Lambda endpoint with per-unit scenario sets.\n\n### 8. Result\n\nFor the example brief above, the run produced:\n\n- **Spec:** `watdonchan/specs/20260407-tefl_teens_13_14/spec.md` — research-grounded, with 15 cited pedagogical principles and corpus-derived L1 targets\n- **Plan + tasks:** in the same directory\n- **Course output:** 60 standalone HTML files (`watdonchan/HTML/tefl/teens_13_14/`) — 12 units × 5 page types (Lesson, Live Chat, Reading + Listening, Quest Quiz, Project & Portfolio) — plus syllabus and portfolio dashboard\n- **Media:** 12 HeyGen avatar videos + ~80 FLUX-generated images, served from S3 via CloudFront\n- **Live chatbot:** every unit has a per-topic NVIDIA NIM scenario set wired to the production Lambda endpoint\n\n### Key patterns\n\n- **One prompt in, complete course out** — the skill orchestrates everything between\n- **Auth-first** — every optional service is checked at Step 0, so you know upfront what you'll get\n- **Pause-and-confirm at each buddy phase** — you review `spec.md` before plan, `plan.md` before tasks, `tasks.md` before implementation. No wasted generation.\n- **Unit 1 verification gate** — bulk generation never runs against an unverified template\n- **Research-grounded by default** — Tavily citations are the evidence base for design decisions; NotebookLM provides per-unit Q&A grounding when available\n- **Pluggable backends** — every backend is optional and degrades gracefully\n\n### Skip the discovery phase\n\nIf you already have a course config JSON, you can skip discovery and Phase 1 entirely by referencing it:\n\n```\n/lesson-builder use config/business_english.json\n```\n\nThe skill loads the config, runs Step 0 auth checks, and jumps straight to the implementation phase. Useful for re-generating an existing course or building from a hand-crafted spec.\n\n## What It Generates\n\nEach unit produces standalone HTML/CSS/JS files with no external dependencies (except Google Fonts). Everything is bilingual — learner's language (L1) first, target language (L2) second.\n\n| Page Type | What It Does |\n|-----------|-------------|\n| 📄 **Lesson** | Vocabulary cards, grammar focus, guided tutorials, section quizzes, homework |\n| 📝 **Activities** | 5-6 exercises per unit with Easy/Medium/Hard difficulty badges |\n| 📝 **Exam** | Interactive exam engine with difficulty selector, score tracking, and gradebook |\n| 🃏 **Flashcards** | Flip cards with pronunciation audio, shuffle, keyboard navigation |\n| 💬 **Conversation** | Dialogue role-play scenarios with speech bubbles and comprehension questions |\n| 🔊 **Pronunciation** | Minimal pairs, listen-and-repeat drills, tongue twisters targeting L1 interference |\n| 🖨️ **Worksheet** | Print-optimized exercises with hidden answer key |\n| 📊 **Syllabus** | Course overview with week navigation, scope table, and assessment rubric |\n\n## Architecture\n\nLesson Builder is a single Claude Code skill that orchestrates a four-phase pipeline adapted from the buddy workflow (`spec → plan → tasks → implement`). It is **auth-first, research-pluggable, and generation-gated**: every invocation begins by checking which optional services are available, then picks the highest-quality research backend that fits, then commits to a single Python generator script that produces all course HTML in one batch — but only after a Unit 1 verification gate has passed.\n\n```mermaid\nflowchart TD\n    %% Inputs\n    User[\"User Input<br/>topic · L1·L2 · age · page types · n_units\"]\n    Config[(\"Optional<br/>course config<br/>JSON\")]\n\n    %% Step 0 — parallel auth checks\n    subgraph S0[\"Step 0 — Service Auth Checks (parallel)\"]\n        NB[\"NotebookLM<br/>auth check\"]\n        TV[\"Tavily Research<br/>tvly auth status\"]\n        RP[\"Replicate<br/>API token check\"]\n    end\n\n    User --> S0\n    Config --> S0\n\n    %% Phase 1 — Spec\n    S0 --> P1[\"Phase 1 — Spec<br/>(buddy:spec pattern)\"]\n    P1 -->|\"copies templates/buddy/spec.md\"| Spec[(\"specs/YYYYMMDD-course_id/<br/>spec.md\")]\n\n    %% Phase 2 — Research + Plan\n    Spec --> P2[\"Phase 2 — Research &amp; Plan<br/>(buddy:plan pattern)\"]\n    P2 --> RBranch{\"Which research<br/>backend?\"}\n    RBranch -->|\"Tavily + NotebookLM\"| Bridge[\"Tavily → NotebookLM bridge<br/>tvly research --json<br/>→ ingest URLs + reports\"]\n    RBranch -->|\"NotebookLM only\"| NBOnly[\"notebooklm source add-research<br/>+ ask loop\"]\n    RBranch -->|\"Tavily only\"| TVOnly[\"tvly research -o research.md\"]\n    RBranch -->|\"neither\"| Web[\"Web Search<br/>(2+ authoritative sources)\"]\n    Bridge --> Research[(\"research.md<br/>+ plan.md\")]\n    NBOnly --> Research\n    TVOnly --> Research\n    Web --> Research\n\n    %% Phase 3 — Tasks\n    Research --> P3[\"Phase 3 — Tasks<br/>(buddy:tasks pattern)<br/>T001–T009\"]\n    P3 --> Tasks[(\"tasks.md\")]\n\n    %% Phase 4 — Implement\n    Tasks --> P4[\"Phase 4 — Implement<br/>(buddy:implement pattern)\"]\n    P4 --> Gen[\"generate_{course_id}.py<br/>one function per page type\"]\n    Gen --> Unit1[\"Generate Unit 1 only<br/>(verification gate)\"]\n    Unit1 --> Verify{\"Browser<br/>verify?\"}\n    Verify -->|\"fails\"| Gen\n    Verify -->|\"passes\"| Bulk[\"Generate units 2…N\"]\n    Bulk --> Polish[\"Cross-file consistency<br/>nav footers · syllabus\"]\n\n    %% Optional images\n    Polish --> ImgCheck{\"Replicate<br/>available?\"}\n    ImgCheck -->|\"yes\"| Imgs[\"generate_images.py<br/>FLUX Dev hero images\"]\n    ImgCheck -->|\"no\"| Out\n    Imgs --> Out\n\n    %% Output\n    Out[(\"HTML/courses/course_id/<br/>standalone bilingual HTML files<br/>+ syllabus + optional images\")]\n\n    %% Styling\n    classDef input fill:#fff3e0,stroke:#ff9800,color:#000\n    classDef artifact fill:#e3f2fd,stroke:#2196f3,color:#000\n    classDef phase fill:#f3e5f5,stroke:#9c27b0,color:#000\n    classDef decision fill:#fffde7,stroke:#fbc02d,color:#000\n    class User,Config input\n    class Spec,Research,Tasks,Out artifact\n    class P1,P2,P3,P4 phase\n    class RBranch,Verify,ImgCheck decision\n```\n\n### Pipeline Phases\n\n| Phase | Pattern | Produces | Purpose |\n|---|---|---|---|\n| **Phase 1 — Spec** | `buddy:spec` | `spec.md` | Course identity, unit breakdown, vocab lists, page types, theme, acceptance criteria. Copied from `templates/buddy/spec.md` and filled in interactively or from a config. |\n| **Phase 2 — Research & Plan** | `buddy:plan` | `research.md`, `plan.md` | Cited research from the best available backend, plus an implementation plan with generator script architecture, content per unit, and risk assessment. |\n| **Phase 3 — Tasks** | `buddy:tasks` | `tasks.md` | Ordered work breakdown (T001–T009). Load-bearing rule: T005 (Unit 1) and T006 (browser verify) form a hard gate before bulk generation. |\n| **Phase 4 — Implement** | `buddy:implement` | Generator script + HTML output | Writes one Python script per course, runs it on Unit 1 first, verifies in browser, then bulk-generates remaining units. |\n\nA complete worked example lives in `specs/EXAMPLE-tefl_children_10_12/` — Thai children ages 10-12, 12 units, 84 HTML files. Read it before starting a new course to see the proven shape of each artifact.\n\n### Pluggable Research Backends\n\nPhase 2 selects a research method automatically based on what Step 0 detected. The skill always picks the highest-quality backend that's actually available, with graceful degradation:\n\n| Available | Method | Quality |\n|---|---|---|\n| Tavily Research **+** NotebookLM | **Tavily → NotebookLM bridge** — `tvly research --json` produces cited reports, citation URLs are ingested into NotebookLM as URL sources, then the existing `notebooklm ask` loop runs against the enriched corpus | Best |\n| NotebookLM only | Plain `notebooklm source add-research` + `ask` loop | Good |\n| Tavily only | `tvly research -o research.md`, no Q&A grounding | Good |\n| Neither | Built-in web search, 2+ authoritative sources | Adequate |\n| User opts for speed | Training data only | Fast but unverified |\n\n### Generation Strategy\n\nA single Python generator script per course (`generate_{course_id}.py`) produces all HTML files in one batch. Each page type is a function (`generate_lesson`, `generate_exam`, `generate_flashcards`, …). Pages are intentionally **standalone** — inline CSS and JS, no external bundles, no runtime dependencies beyond Google Fonts. This means every page works on any static host, in any browser, with no build step.\n\nThe Unit 1 verification gate is the load-bearing rule that keeps generation reliable: the script generates only Unit 1 first, the user opens every page in a browser to confirm interactive features work and there are no JS errors, *then* the remaining units are generated using the same templates. No bulk generation runs against an unverified template.\n\n### Repo Layout\n\n```\nlesson-builder/\n├── SKILL.md                          # The skill itself (read by Claude Code)\n├── README.md                         # This file\n├── config/                           # Course config JSONs (12-week TEFL examples)\n├── templates/\n│   ├── *.json                        # Course config templates (business, IT, starter)\n│   ├── children_pages/               # Children's page-type specs + examples (ages 4-12)\n│   │   ├── README.md                 # Page-type catalog + song video IDs\n│   │   ├── story_example.html        # Minimal story page (Dr. Seuss rhyming)\n│   │   ├── game_example.html         # Minimal game page (Match/Tap/Memory)\n│   │   └── coloring_example.html     # Minimal coloring page (two-canvas)\n│   ├── notebooklm/\n│   │   └── query_patterns.md         # Query phrasing tips + auth troubleshooting\n│   ├── images/\n│   │   ├── README.md                 # generate_images.py usage + emoji color tables\n│   │   └── prompt_style_prefix.txt   # Coloring page style prefix (copy-pasteable)\n│   └── buddy/                        # Buddy workflow artifact templates\n│       ├── spec.md                   # Phase 1 skeleton\n│       ├── plan.md                   # Phase 2 skeleton\n│       ├── tasks.md                  # Phase 3 skeleton\n│       └── research.md               # Phase 2 research notes skeleton\n└── specs/\n    └── EXAMPLE-tefl_children_10_12/  # Complete worked example (5 artifacts)\n```\n\n## Example Use Cases\n\n**Language Schools & TEFL Programs**\n- Thai→English, Japanese→English, Spanish→English — any L1→L2 pair\n- CEFR-aligned courses from Pre-A1 through B1+\n- Classroom supplements with printable worksheets and exam score tracking\n\n**Vocational & Career Training**\n- English through IT — teach networking, cybersecurity, or web dev vocabulary in English\n- Business English — meetings, email, presentations\n- Medical or hospitality English — domain-specific vocabulary for career pathways\n\n**Self-Paced E-Learning**\n- Host on S3, GitHub Pages, or any static server — no backend required\n- Full 12-week courses from a single JSON config\n- One-off lessons on any topic in minutes\n\n**Content at Scale**\n- Python generator scripts produce dozens of pages at once\n- JSON configs make courses repeatable and version-controlled\n- Mix and match page types per unit — exams every week, flashcards for 3 random units, pronunciation drills at weeks 6, 9, and 12\n\n## Configuration\n\nDefine a reusable course as a JSON config. Control everything — languages, page types per unit, section structure, color theme, and vocabulary targets.\n\n```jsonc\n{\n  \"course_id\": \"my_course\",\n  \"l1\": \"th\", \"l2\": \"en\",\n  \"output_dir\": \"HTML/courses/my_course\",\n  \"theme\": { \"primary\": \"#f97316\" },\n\n  \"page_types\": {\n    \"lesson\": \"every\",\n    \"exam\": \"every\",\n    \"flashcards\": \"random:3\",\n    \"conversation\": \"random:4\",\n    \"pronunciation\": \"units:6,9,12\",\n    \"syllabus\": true\n  },\n\n  \"units\": [ ... ]\n}\n```\n\nSee [`config/schema.md`](skills/lesson-builder/config/schema.md) for the full specification and examples.\n\n## Optional Integrations\n\nThese are not required — the skill works standalone using Claude's training data.\n\n| Integration | What It Does |\n|-------------|-------------|\n| [NotebookLM](https://github.com/teng-lin/notebooklm-py) | AI-powered research to verify course content against authoritative sources |\n| [Tavily Research](https://github.com/tavily-ai/skills) | Deep cited research via the `tvly` CLI; can feed citation URLs and synthesized reports directly into NotebookLM as sources |\n| `fact-checker` skill | Validates grammar rules, translations, and quiz answers before generation |\n| [Replicate](https://replicate.com) | AI image generation (FLUX Dev) for lesson illustrations (~$0.03/image) |\n\n### Optional: Secrets Manager Auto-Login\n\nIf you store API keys in a secrets manager (AWS SSM Parameter Store, AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault, 1Password CLI, etc.), the skill's Step 0 auth checks can pull credentials from there automatically instead of prompting the user.\n\nFor example, with **AWS SSM Parameter Store** and the AWS CLI configured:\n\n```bash\n# In Step 0b, if `tvly auth` reports unauthenticated:\nTAVILY_KEY=$(aws ssm get-parameter --name tavily --with-decryption \\\n  --region us-west-2 --query 'Parameter.Value' --output text 2>/dev/null)\n[ -n \"$TAVILY_KEY\" ] && tvly login --api-key \"$TAVILY_KEY\"\n```\n\nAdapt the lookup line to whatever secrets backend you use. The skill's auth check just needs to end with `tvly login --api-key` (or the equivalent for NotebookLM / Replicate). This pattern keeps API keys out of `.env` files and out of shell history while still letting the skill bootstrap itself non-interactively on a fresh machine.\n\n## Built With This\n\n**[krueng.ai](https://krueng.ai)** — A 6-course IT career training program teaching English through technology to Thai learners at Wat Don Chan, Chiang Mai. 72 weeks of lessons, activities, and exams across Digital Foundations, IT Essentials, AI & English, Networking, Help Desk, and Security.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 19155,
  "sha": "44f33d3b80cd43e5213b96d6cb0b8f5f67d516a147d098a7adaecbe9ce8e8b07",
  "repo_slug": "ddtraveller/lesson-builder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ddtraveller_lesson_builder_lesson_builde_f7fd2125/readme"
}