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.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-dataSkill
- brainstormingSkill
- create-agentSkill
- create-skillSkill
- customize-agentSkill
- customize-skillSkill
- designSkill
- deslopSkill
- developSkill
- discovery-reportSkill
- elicitationSkill
- empathy-mapSkill
- explore-ideaSkill
- grill-meSkill
- help-meSkill
- humanizeSkill
- incidentSkill
- iterateSkill
- journey-mapSkill
- jtbdSkill
- kanbanSkill
- launchSkill
- legal-safety-auditSkill
- maintenance-executeSkill
- maintenance-planSkill
- memorySkill
- motionSkill
- phaseSkill
- planSkill
- research-planSkill
- retroSkill
- reviewSkill
- root-causeSkill
- round-tableSkill
- shape-upSkill
- shut-upSkill
- statusSkill
- teach-meSkill
- testSkill
- unpack-problemSkill
- validate-ideaSkill
- validation-patternsSkill
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
- Distinctive: line 46
Every selected format has been individually generated, presented, and explicitly approved
- Very specific: line 138
If teaching-style.md does NOT exist, run Guided Onboarding:
- Very specific: line 143
Ask user which format(s) to generate (or specify --all):
- Very specific: line 150
Default if unspecified: syllabus + handbook + cheatsheet.
- Very specific: line 171
If Mode 2 (Draft/Transcript): Execute step-02b-synthesize.md (.agents/skills/craft-lesson/steps/step-02b-synthesize.md).
- Distinctive: line 213
After the user approves a deliverable, record it in the pipeline state AND refresh project-context/session activity via the orchestrator.
- Distinctive: line 230
All output files MUST be written.
- Distinctive: line 241
Do NOT generate the next format until the current one is explicitly approved.
- Distinctive: line 242
Do NOT present multiple formats for review at once — one at a time, always.
≈ “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.
Files
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.
@shifupersona configuration (.agents/agents/shifu.md).- Output directory
artifacts/output/teaching/accessible for file delivery.
Halt conditions
- A Presentation-intake question is unanswered while
presentationis among the selected formats -> do NOT proceed to Phase 2;--allselects 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.mdcannot be written (no@memory-controllerwrite 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 completecall — milestones are recorded as they happen, never batched at the end knowledge-map.mdand all approved deliverables exist underartifacts/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| Rule | What is checked |
| Record hygiene | no unfilled template placeholders — a map still carrying {...} is the template |
| Bloom's tagging | Phase 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 anchors | an "If Nothing Else, Remember This" anchor is present, as Phase 3 declares |
| Sequencing | at 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
- Mode 1: Topic-Only (Research Path)
- User provides a topic (e.g.
/craft-lesson "Distributed Consensus"). @shifudelegates comprehensive research to@researcher(Iris) to gather foundational concepts, paradigms, edge cases, and industry standards before structuring.
- User provides a topic (e.g.
- Mode 2: Draft / Transcript / Notes (Synthesis Path)
- User provides raw content (e.g.
/craft-lesson --file=drafts/lecture-notes.txtor pastes raw transcript). @shifureads and extracts key concepts, identifies knowledge gaps, and organizes unstructured ideas into pedagogical form.
- User provides raw content (e.g.
Supported Output Formats
| Format Identifier | Target Deliverable Path | Description |
syllabus | artifacts/output/teaching/syllabus.md | Course syllabus: learning objectives, module roadmap, timing, assessment plan. |
handbook | artifacts/output/teaching/handbook.md | Comprehensive, detailed textbook/handbook (full narrative depth; not a cheatsheet). |
cheatsheet | artifacts/output/teaching/cheatsheet.md | Scannable quick reference, decision trees, cheat tables, key formulas. |
presentation | artifacts/output/teaching/presentation.md | Slide 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. |
class | artifacts/output/teaching/class/ | Online class package: module units, readings, hands-on exercises, quizzes. |
video-script | artifacts/output/teaching/video-script.md | Production video script with transcript, timecodes, camera/visual cues. |
5-Phase Master Workflow
flowchart TD
P1["Phase 1: Intake & Setup<br/>Select input mode, audience level & 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 & 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| P5Phase Details & Step File Routing
Phase 1: Intake & Format Selection Intake
Tracker:
node .agents/scripts/step_tracker.js begin --skill craft-lesson --step 1
- Input Mode Detection:
- Determine whether the input is a Topic-only string or a Draft/Transcript file/text.
- 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.,
handbookfor developers,presentationfor executives,cheatsheetfor architects). - Load
artifacts/memory/teaching-style.mdvia@memory-controllerand use what it says. It already carriesExplanation Style,Primary Target Audience,Prerequisite Level,Tone Style,Jargon Policy,Analogy Densityand 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.mddoes NOT exist, run Guided Onboarding:- Prompt user for target audience profile & depth style (
Beginner,Intermediate, orExpert). - Prompt user for preferred section patterns and default format selections.
- Delegate saving
teaching-style.mdto@memory-controller.
- Prompt user for target audience profile & depth style (
- Format Selection Intake:
- Ask user which format(s) to generate (or specify
--all):1. Syllabus2. Handbook3. Cheatsheet4. Presentation Outline5. Online Class Modules6. Video Script
- Default if unspecified:
syllabus+handbook+cheatsheet.
- Ask user which format(s) to generate (or specify
- Per-Format Mandatory Intake Gates (NON-NEGOTIABLE):
[!IMPORTANT] Selecting a format — including via
--all— does NOT waive its mandatory intake questions.--allonly selects the formats; it never answers their audience/style/budget questions for you. Ifpresentationis among the selected formats,@shifuMUST ask the user the 4 Presentation Intake Questions in this Phase 1, BEFORE any research, synthesis, or knowledge-map work:- Audience Scope & Profile: Internal (Company/Team roles & topic level) or External (Public/Course target group & background)?
- Presentation Style Archetype: 🎓 EdTech Masterclass, 🎯 Executive Briefing, 🌟 Keynote Narrative, 🛠️ Technical Deep-Dive, 📚 Educational Workshop, 💼 Product Pitch, or ⚡ Lightning Blitz?
- Opening Hook Archetype: ❓ Socratic Question, 💥 Pain Point, 📊 Provocative Fact, 📖 Micro-Story, 🎯 Direct BLUF, or ⚡ Before vs. After Contrast?
- 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.
@shifuMUST 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 53b. 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):
- Syllabus Step:
step-04a-syllabus.md$\rightarrow$artifacts/output/teaching/syllabus.md - Handbook Step:
step-04b-handbook.md$\rightarrow$artifacts/output/teaching/handbook.md - Cheatsheet Step:
step-04c-cheatsheet.md$\rightarrow$artifacts/output/teaching/cheatsheet.md - Presentation Step:
step-04d-presentation.md$\rightarrow$artifacts/output/teaching/presentation.md - Online Class Step:
step-04e-class.md$\rightarrow$artifacts/output/teaching/class/ - 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
completecalls. - 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:
- Style Fidelity Audit: Verifies text matches target style (
Beginner,Intermediate, orExpert). - Jargon & Clarity Audit: Ensures all introduced technical terms are defined upon first use.
- 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 Phase | Responsible Agent | Operational I/O | Key Deliverables |
| Phase 1: Intake | @shifu | @memory-controller | Preference state loaded |
| Phase 2a: Research | @shifu | @researcher (Iris) | Raw domain research |
| Phase 2b: Synthesize | @shifu | Direct I/O | Parsed draft synthesis |
| Phase 3: Knowledge Map | @shifu | Direct I/O | artifacts/output/teaching/knowledge-map.md |
| Phase 4: Formats | @shifu | Direct I/O | ONE format deliverable per loop iteration in artifacts/output/teaching/, each human-verified + recorded via orchestrator_state.js complete before the next |
| Phase 5: Review | @shifu | Direct I/O / User | Quality 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 listsDirect I/Ofor 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:@shifuwrites, and only memory operations delegate.
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
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.

