agentleFS
lalulalilalulali/vespyr/.agents/skills/craft-lesson/SKILL.md

craft-lesson

Skill11 starsChanged 11 days agoMITView on GitHub

Create multi-format educational materials (syllabus, handbook, cheatsheet, presentation, class, video script) from topic or draft. Use when the user says "build a course", "turn this transcript into a handbook", "make a cheatsheet", "draft a video script", or invokes /craft-lesson.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every selected format has been individually generated, presented, and explicitly approved

    line 46
  2. Very specific:

    If teaching-style.md does NOT exist, run Guided Onboarding:

    line 138
  3. Very specific:

    Ask user which format(s) to generate (or specify --all):

    line 143
  4. Very specific:

    Default if unspecified: syllabus + handbook + cheatsheet.

    line 150
  5. Very specific:

    If Mode 2 (Draft/Transcript): Execute step-02b-synthesize.md (.agents/skills/craft-lesson/steps/step-02b-synthesize.md).

    line 171
  6. Distinctive:

    After the user approves a deliverable, record it in the pipeline state AND refresh project-context/session activity via the orchestrator.

    line 213
  7. Distinctive:

    All output files MUST be written.

    line 230
  8. Distinctive:

    Do NOT generate the next format until the current one is explicitly approved.

    line 241
  9. Distinctive:

    Do NOT present multiple formats for review at once — one at a time, always.

    line 242

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Craft-Lesson — Multi-Format Educational Material Generator

<!-- router-skill -->

What this skill does

Takes any topic, lecture draft, raw notes, video transcript, or domain documentation and transforms it into a unified suite of up to 6 distinct educational formats derived from a single master Knowledge Map. Governed by @shifu (Kong Qiu) using Feynman principles, Oakley cognitive load controls, and Bloom's taxonomy objectives.

Persona delegation

This skill delegates pedagogical strategy, objective framing, content sequencing, and quality review to @shifu (Kong Qiu). All file I/O operations are performed directly; memory operations delegate to @memory-controller, and external research to @researcher.

When to use

  • "Create a course syllabus and student handbook for Rust Async Programming"
  • "Turn this product architecture transcript into a cheatsheet and presentation deck"
  • "Build an online class module with quizzes on Financial Literacy"
  • "Draft a 10-minute video script explaining Vector Databases for Beginners"
  • Trigger command: /craft-lesson

Prerequisites

  • Input topic name OR existing text draft/transcript file.
  • @shifu persona configuration (.agents/agents/shifu.md).
  • Output directory artifacts/output/teaching/ accessible for file delivery.

Halt conditions

  • A Presentation-intake question is unanswered while presentation is among the selected formats -> do NOT proceed to Phase 2; --all selects formats, it never answers their intake questions for you
  • The Knowledge Map has not been signed off by the user -> format generation is blocked; formats derive from the map, not from ad-hoc per-format invention
  • A format is generated without a human approval on the previous one -> halt; Phase 4 is one-at-a-time by contract, and batching is the exact failure mode this gate exists to stop
  • teaching-style.md cannot be written (no @memory-controller write access) -> halt; guessing at audience and depth produces material the user cannot use

Done when

  • Every selected format has been individually generated, presented, and explicitly approved
  • Each approval triggered its own orchestrator_state.js complete call — milestones are recorded as they happen, never batched at the end
  • knowledge-map.md and all approved deliverables exist under artifacts/output/teaching/
  • Step 5's three audit vectors (style fidelity, jargon clarity, pedagogical alignment) have run and the user has confirmed the final summary

Checked mechanically — and the part that cannot be

node .agents/scripts/teaching_artifact_check.js check \
  --kind knowledge-map --file artifacts/output/teaching/knowledge-map.md --json
RuleWhat is checked
Record hygieneno unfilled template placeholders — a map still carrying {...} is the template
Bloom's taggingPhase 3 requires every objective tagged, and at least three distinct tiers. A map whose every objective sits at [REMEMBER] is a list, not a Prerequisites → Core → Advanced sequence
Takeaway anchorsan "If Nothing Else, Remember This" anchor is present, as Phase 3 declares
Sequencingat least one of the three declared bands is named. Naming only one prints a note rather than failing, because section naming is the author's

What no gate can check, stated rather than implied: whether you paused. The centrepiece of Phase 4 is "generate ONE format, present it, PAUSE for approval, only then continue" — and a script cannot see a pause. What it can see is the evidence a pause leaves behind: one orchestrator_state.js complete call per approved format. Verify that sequence by reading the milestone records, not by reading a green line here. The gate checks the artifacts, never the approvals.

2 Input Modes

  1. Mode 1: Topic-Only (Research Path)
    • User provides a topic (e.g. /craft-lesson "Distributed Consensus").
    • @shifu delegates comprehensive research to @researcher (Iris) to gather foundational concepts, paradigms, edge cases, and industry standards before structuring.
  2. Mode 2: Draft / Transcript / Notes (Synthesis Path)
    • User provides raw content (e.g. /craft-lesson --file=drafts/lecture-notes.txt or pastes raw transcript).
    • @shifu reads and extracts key concepts, identifies knowledge gaps, and organizes unstructured ideas into pedagogical form.

Supported Output Formats

Format IdentifierTarget Deliverable PathDescription
syllabusartifacts/output/teaching/syllabus.mdCourse syllabus: learning objectives, module roadmap, timing, assessment plan.
handbookartifacts/output/teaching/handbook.mdComprehensive, detailed textbook/handbook (full narrative depth; not a cheatsheet).
cheatsheetartifacts/output/teaching/cheatsheet.mdScannable quick reference, decision trees, cheat tables, key formulas.
presentationartifacts/output/teaching/presentation.mdSlide outline (1 key idea per slide) with detailed speaker notes & visual cues. Supports 7 presentation styles (including EdTech Masterclass), 2-step audience profiling, and 6 opening hook archetypes.
classartifacts/output/teaching/class/Online class package: module units, readings, hands-on exercises, quizzes.
video-scriptartifacts/output/teaching/video-script.mdProduction video script with transcript, timecodes, camera/visual cues.

5-Phase Master Workflow

flowchart TD
  P1["Phase 1: Intake &amp; Setup<br/>Select input mode, audience level &amp; format targets"]
  P2A["Phase 2a: Research<br/>(Topic-Only Path via step-02a-research.md)"]
  P2B["Phase 2b: Synthesize<br/>(Draft/Transcript Path via step-02b-synthesize.md)"]
  P3["Phase 3: Master Knowledge Map Creation<br/>Bloom's taxonomy tagging, sequencing,<br/>'If Nothing Else' anchors<br/>Output: artifacts/output/teaching/knowledge-map.md<br/>(via step-03-structure.md)"]
  P4["Phase 4: ONE format at a time + HUMAN VERIFY loop"]
  LOOP{"approved?"}
  NEXT["next format (loop)"]
  REV["revise, re-present, PAUSE again"]
  P5["Phase 5: Self-Review &amp; Quality Certification<br/>Style audit, jargon check, pedagogical verification<br/>(via step-05-review.md)<br/>runs AFTER all formats approved"]

  P1 --> P2A --> P3
  P1 --> P2B --> P3
  P3 --> P4 --> LOOP
  LOOP -->|yes| NEXT --> P4
  LOOP -->|changes requested| REV --> P4
  LOOP -->|all formats approved| P5

Phase Details & Step File Routing

Phase 1: Intake & Format Selection Intake

Tracker: node .agents/scripts/step_tracker.js begin --skill craft-lesson --step 1

  1. Input Mode Detection:
    • Determine whether the input is a Topic-only string or a Draft/Transcript file/text.
  2. Universal Upfront Audience & Style Calibration:
    • Establish the target audience profile upfront before doing ANY research or mapping.
    • Step 1: Audience Scope: Internal (Company/Team roles & topic level) vs. External (Public/Course target group & background).
    • Step 2: Format-Specific Audience Mapping: Determine if specific deliverable targets require audience differentiation (e.g., handbook for developers, presentation for executives, cheatsheet for architects).
    • Load artifacts/memory/teaching-style.md via @memory-controller and use what it says. It already carries Explanation Style, Primary Target Audience, Prerequisite Level, Tone Style, Jargon Policy, Analogy Density and per-format preferences. Present those as the defaults and ask only for what the file does not answer — a load whose values are then re-asked from the user is decoration, and it makes the learner answer the same question every run.
    • If teaching-style.md does NOT exist, run Guided Onboarding:
      • Prompt user for target audience profile & depth style (Beginner, Intermediate, or Expert).
      • Prompt user for preferred section patterns and default format selections.
      • Delegate saving teaching-style.md to @memory-controller.
  3. Format Selection Intake:
    • Ask user which format(s) to generate (or specify --all):
      • 1. Syllabus
      • 2. Handbook
      • 3. Cheatsheet
      • 4. Presentation Outline
      • 5. Online Class Modules
      • 6. Video Script
    • Default if unspecified: syllabus + handbook + cheatsheet.
  4. Per-Format Mandatory Intake Gates (NON-NEGOTIABLE):

    [!IMPORTANT] Selecting a format — including via --all — does NOT waive its mandatory intake questions. --all only selects the formats; it never answers their audience/style/budget questions for you. If presentation is among the selected formats, @shifu MUST ask the user the 4 Presentation Intake Questions in this Phase 1, BEFORE any research, synthesis, or knowledge-map work:

    1. Audience Scope & Profile: Internal (Company/Team roles & topic level) or External (Public/Course target group & background)?
    2. Presentation Style Archetype: 🎓 EdTech Masterclass, 🎯 Executive Briefing, 🌟 Keynote Narrative, 🛠️ Technical Deep-Dive, 📚 Educational Workshop, 💼 Product Pitch, or ⚡ Lightning Blitz?
    3. Opening Hook Archetype: ❓ Socratic Question, 💥 Pain Point, 📊 Provocative Fact, 📖 Micro-Story, 🎯 Direct BLUF, or ⚡ Before vs. After Contrast?
    4. Time & Slide Budget: Target duration & slide count (e.g. 10 mins / 8 slides, 30 mins / 15 slides, 60 mins / 25 slides)? Calibrate to ~1.5–2 minutes per slide. Do NOT proceed to Phase 2 until all 4 are answered (unless the user explicitly supplied all 4 in their original prompt).

Tracker: node .agents/scripts/step_tracker.js complete --skill craft-lesson --step 1


Phase 2: Knowledge Extraction (Route by Mode)

  • If Mode 1 (Topic-Only): Execute step-02a-research.md (.agents/skills/craft-lesson/steps/step-02a-research.md). Delegates domain research to @researcher (Iris), extracts core principles, and establishes concept boundaries.
  • If Mode 2 (Draft/Transcript): Execute step-02b-synthesize.md (.agents/skills/craft-lesson/steps/step-02b-synthesize.md). Reads the file, parses raw text, identifies missing prerequisites, and structures raw insights.

Phase 3: Master Knowledge Map Creation

Execute step-03-structure.md (.agents/skills/craft-lesson/steps/step-03-structure.md). @shifu synthesizes all extracted research/notes into artifacts/output/teaching/knowledge-map.md:

  • Tag every objective with Bloom's Taxonomy Level:
    • [REMEMBER] — Recall facts & basic concepts
    • [UNDERSTAND] — Explain ideas or concepts
    • [APPLY] — Use information in new situations
    • [ANALYZE] — Draw connections among ideas
    • [EVALUATE] — Justify a stand or decision
    • [CREATE] — Produce new or original work
  • Establish logical dependency sequencing (Prerequisites $\rightarrow$ Core $\rightarrow$ Advanced).
  • Define "If Nothing Else, Remember This" takeaway anchors per section.

User Approval Gate: Present Knowledge Map summary to user for sign-off before format generation.


Phase 4: Format Generation — ONE AT A TIME with Human Verification (NON-NEGOTIABLE)

[!IMPORTANT] Generate one document, then stop and wait for human verification. Do NOT batch-produce all formats in a single turn. @shifu MUST process the selected formats sequentially: produce exactly ONE deliverable, present it for review, pause, and only continue to the next format after the user verifies/approves. This applies even when the user selected multiple formats or said --all.

The loop (repeat for each selected format, in this exact order):

1. GENERATE  → produce ONE deliverable (the next unstarted format in the list)
2. PRESENT   → show the user a summary of what was generated + where it is saved
3. VERIFY    → PAUSE. Ask the user to review it and approve, or request changes
   ├── APPROVED  → RECORD milestone (step 3b), mark format complete, next format (step 1)
   └── CHANGES   → incorporate the requested changes, re-present, PAUSE again
4. Only after the LAST selected format is approved → proceed to Phase 5

3b. RECORD MILESTONE (after EVERY approval — NON-NEGOTIABLE): After the user approves a deliverable, record it in the pipeline state AND refresh project-context/session activity via the orchestrator. Run:

node .agents/scripts/orchestrator_state.js complete --agent shifu --artifact artifacts/output/teaching/{deliverable}.md --next "{next deliverable, or 'all done'}"

This is what updates project-context.md (## Session Activity, Phase/Blockers/Repository/Stack/Runtime state) and records the artifact as completed. Do NOT defer all recording to the end of the workflow — each approved deliverable is a milestone boundary and MUST be recorded immediately. If the user stops after a single format, the context still reflects that milestone.

Format generation order (generate in list order, skipping any the user did not select):

  1. Syllabus Step: step-04a-syllabus.md $\rightarrow$ artifacts/output/teaching/syllabus.md
  2. Handbook Step: step-04b-handbook.md $\rightarrow$ artifacts/output/teaching/handbook.md
  3. Cheatsheet Step: step-04c-cheatsheet.md $\rightarrow$ artifacts/output/teaching/cheatsheet.md
  4. Presentation Step: step-04d-presentation.md $\rightarrow$ artifacts/output/teaching/presentation.md
  5. Online Class Step: step-04e-class.md $\rightarrow$ artifacts/output/teaching/class/
  6. Video Script Step: step-04f-video-script.md $\rightarrow$ artifacts/output/teaching/video-script.md

All output files MUST be written.

Verification prompt format (use at every gate):

✅ {Format} generated → {relative file path}

What's in it: {1–2 sentence summary}

Please review it. Reply "approved" to continue to the next format, or tell me what to change and I'll revise it before continuing.

Rules:

  • Do NOT generate the next format until the current one is explicitly approved.
  • Do NOT present multiple formats for review at once — one at a time, always.
  • Record each approved deliverable immediately (step 3b) — never batch the complete calls.
  • The Knowledge Map is the shared source for all formats; it is created once in Phase 3, not re-generated per format.

Phase 5: Self-Review & Quality Certification

Run ONLY after every selected format has been individually approved in Phase 4.

Execute step-05-review.md (.agents/skills/craft-lesson/steps/step-05-review.md). @shifu performs an audit across 3 check vectors:

  1. Style Fidelity Audit: Verifies text matches target style (Beginner, Intermediate, or Expert).
  2. Jargon & Clarity Audit: Ensures all introduced technical terms are defined upon first use.
  3. Pedagogical Alignment Gate: Confirms all format deliverables match objectives in knowledge-map.md.

User Approval Gate: Present final summary, list generated artifacts with file links, and seek user confirmation.


Delegation Matrix

Workflow PhaseResponsible AgentOperational I/OKey Deliverables
Phase 1: Intake@shifu@memory-controllerPreference state loaded
Phase 2a: Research@shifu@researcher (Iris)Raw domain research
Phase 2b: Synthesize@shifuDirect I/OParsed draft synthesis
Phase 3: Knowledge Map@shifuDirect I/Oartifacts/output/teaching/knowledge-map.md
Phase 4: Formats@shifuDirect I/OONE format deliverable per loop iteration in artifacts/output/teaching/, each human-verified + recorded via orchestrator_state.js complete before the next
Phase 5: Review@shifuDirect I/O / UserQuality review & delivery log (after all formats approved)

Anti-Patterns to Avoid

  • Do NOT batch-produce all selected formats in one turn. Generate one format, pause for human verification, and only continue after explicit approval. One at a time, always.
  • Do NOT bypass Phase 3 Knowledge Map. Formats MUST be generated from a single unified map, not ad-hoc per format.
  • Do NOT mix explanation styles. Maintain consistent style (Beginner vs Intermediate vs Expert) across all selected formats in a single run.
  • Write files directly; do not delegate the write to a sub-agent. This bullet used to read "Do NOT perform direct file writes from @shifu. Always write files directly" — two opposite instructions in one sentence, contradicting the Delegation Matrix above it, which lists Direct I/O for Phases 2b, 3, 4 and 5. An agent following the first clause would route every deliverable through @memory-controller; one following the second would write it itself. Both cannot be the contract, so the matrix wins: @shifu writes, and only memory operations delegate.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.