Guides facilitators through building hands-on workshop modules using a 6-phase learn-then-capture process, producing exercise artifacts, facilitator guides, help agents, and git branch structures.
Codified workflow for building hands-on workshop modules. Derived from the Module 1 (Custom Agents) creation session. Produces: an exercise artifact students build, a facilitator guide with step-by-step instructions, a Socratic help agent, and a git branch structure separating student and facilitator materials.
| Input | Type | Required | Description |
|---|---|---|---|
| module_number | number | Yes | Module number (1-5) |
| module_topic | string | Yes | Topic name (e.g., "Skills", "Subagents", "Hooks") |
| learning_objective | string | Yes | What students should be able to do after completing this module |
| artifact_type | string | Yes | What students build: agent, skill, hook, or config |
| artifact_filename | string | Yes | Target filename students create (e.g., "visual-verifier.agent.md") |
| repo_path | string | No | Workshop repo path (default: ~/Developer/ISG-AI-Workshop) |
| facilitator_worktree | string | No | Facilitator worktree path (default: ~/Developer/worktrees/ISG-AI-Workshop-facilitator) |
| reference_skill | string | No | Skill to use for validating content (default: ghcp) |
| Output | Type | Description |
|---|---|---|
| exercise_artifact | file | The artifact students build, written incrementally |
| facilitator_guide | file | MODULE_N_TOPIC.md in facilitator worktree |
| help_agent | file | module-N-help.agent.md committed to main |
| module_branch | git branch | module-N/start branch from main |
| solution_branch | git branch | module-N/solution with completed artifact |
Create the module branch and establish the working context.
Before starting, search qmd for prior module patterns (skip if qmd unavailable):
Run qmd query "learning module {module_topic}" -C 38 --json --limit 3 -c skill-artifacts
If results with score > 50%, read top docs with qmd get for reusable structure
Incorporate as prior-art context (do not skip phases)
Confirm inputs with the facilitator:
Create the git branch:
cd {repo_path}
git checkout main
git checkout -b module-{N}/start
Confirm the facilitator worktree exists:
ls {facilitator_worktree}/facilitator/modules/
If missing, create it:
git worktree add {facilitator_worktree} -b facilitator main
mkdir -p {facilitator_worktree}/facilitator/modules
Initialize the facilitator guide with the header:
# Module {N}: {Topic} -- Facilitator Guide
## Overview
- Duration: ~{X} minutes
- Outcome: {learning_objective}
- Branch: `module-{N}/start` (students work here), `module-{N}/solution` (reference)
- Prerequisite: {prerequisites}
## Key Concepts to Teach
{numbered list of 5-7 concepts}
## Sad Paths (Instructor Gotchas)
{populated during walkthrough -- start empty}
---
## Steps
Ask the facilitator: "Ready to start the walkthrough? I'll guide you section by section. Say 'keep', 'cut', or 'revise' for each proposal. Say 'capture' when you want to write a facilitator guide step."
The core learning loop. The facilitator acts as a student while the skill acts as instructor.
For each section of the artifact:
Propose content. Present one section at a time with reasoning.
Wait for approval. The facilitator responds:
Write to the artifact file. After approval, append to the exercise artifact at:
{repo_path}/.github/{artifact_type}s/{artifact_filename}
(Adjust path based on artifact_type: agents/ for agents, skills/ for skills, hooks/ for hooks)
Track mistakes. When the instructor (skill) makes an error and the facilitator catches it, log it as a Sad Path. These become teaching material.
Validate with references. After completing each major section, use the reference skill to verify claims:
Use the {reference_skill} skill to validate {section_name}
Interaction rules during walkthrough:
When the facilitator says "capture", write a numbered Step to the facilitator guide.
Step template:
### Step {N}: {Section Name} (~{X} min)
{Context for the facilitator -- what this step teaches and why}
**Facilitator says:**
> "{Opening line to say to students}"
**Teaching approach:** {How to guide students through this section}
**Students add:**
```{language}
{The content students should write}
Key teaching moment:
"{The core insight this step delivers}"
Sad path: {Mistakes the instructor made or common student mistakes}
**Rules for capture:**
- Include any sad paths that occurred during the walkthrough for this section
- Include teaching moments and discussion prompts that emerged
- Reference the actual content from the artifact (not paraphrased)
- Add timing estimates based on complexity (simple: ~3 min, moderate: ~5 min, complex: ~10 min)
After writing each step, sync to the facilitator worktree:
```bash
cp {session_file} {facilitator_worktree}/facilitator/modules/MODULE_{N}_{TOPIC}.md
After completing the walkthrough and all capture steps, create a module-specific help agent.
Invoke the create-agent skill with these parameters:
module-{N}-helpCommit to main so students have it from the start:
git checkout main
git add .github/agents/module-{N}-help.agent.md
git commit -m "Add Module {N} help agent for student assistance"
git checkout module-{N}/start
git rebase main
Test the completed artifact against the real application.
Invoke the artifact:
/agent {name} or --agent={name} with a realistic promptEvaluate the output:
Tighten the spec based on what the artifact actually produced:
Re-capture any steps that changed during tightening.
Create or update the student-facing workshop guide with a section for this module.
Check if docs/WORKSHOP_GUIDE.md exists on main:
git checkout main
ls docs/WORKSHOP_GUIDE.md
If it does not exist, create it with a setup section (prerequisites, repo clone, verification commands) and a workshop overview table.
Add a module section with these elements:
git checkout module-{N}/startmodule-{N}-help"git checkout module-{N}/solutionUpdate the overview table at the top of the guide to include the new module row.
Commit to main:
git add docs/WORKSHOP_GUIDE.md
git commit -m "Add Module {N} to student workshop guide"
Rules for student guides:
Set up the complete branch structure.
Create the solution branch:
git checkout module-{N}/start
git checkout -b module-{N}/solution
git add .github/{artifact_type}s/{artifact_filename}
git commit -m "Add completed {artifact_filename} (Module {N} solution)"
Ensure main has help agents and reference materials:
git checkout main
# Verify help agent is committed
git log --oneline -1 -- .github/agents/module-{N}-help.agent.md
Sync facilitator worktree:
cp {session_facilitator_guide} {facilitator_worktree}/facilitator/modules/MODULE_{N}_{TOPIC}.md
Verify branch structure:
| Branch | Contains | Audience |
|---|---|---|
| main | App + all help agents + reference materials | Students |
| module-{N}/start | main content, exercise artifact untracked | Students |
| module-{N}/solution | Completed artifact committed | Students (post-exercise) |
| facilitator | main + facilitator/ directory | Facilitator only |
Print summary:
=== Module {N}: {Topic} Complete ===
Artifact: {artifact_filename} ({line_count} lines)
Facilitator guide: MODULE_{N}_{TOPIC}.md ({step_count} steps)
Student guide: docs/WORKSHOP_GUIDE.md (Module {N} section added)
Help agent: module-{N}-help.agent.md
Branches: module-{N}/start, module-{N}/solution
Sad paths documented: {count}
Every module's facilitator guide follows this structure:
# Module {N}: {Topic} -- Facilitator Guide
## Overview
- Duration, outcome, branches, prerequisites
## Key Concepts to Teach
- Numbered list of 5-7 core concepts
## Sad Paths (Instructor Gotchas)
- Numbered list of real mistakes from the walkthrough
---
## Steps
### Step 1: {First Section} (~X min)
{Step template as defined in Phase 3}
### Step 2: {Second Section} (~X min)
...
### Step N: Invoke and Test (~5 min)
{Always the final content step}
---
## Facilitator Notes
- Timing tips
- Discussion prompts
- Early finisher challenges
- What to defer to later modules
Before marking a module complete:
After generating output files, persist to qmd for cross-session retrieval:
~/.copilot/kb-export/skill-artifacts/create-learning-module/<date>/qmd update in background (best-effort, skip silently if qmd unavailable)