| name | agent-teaching-mode |
| description | Use when the user wants to learn while building or wants a codebase review explained in a teaching-guide voice. This skill overlays the normal build or review lane and turns the work into guided pair-programming with small code slices, plain-English explanations, jargon definitions, and step-by-step reasoning about what comes next. |
Agent Teaching Mode
This skill is a delivery overlay, not the main builder.
Use it together with the normal build skill when the user wants to:
- build the stack together
- review a codebase while learning how the system fits together
- go one section of code at a time
- understand the jargon as it appears
- learn what each variable, schema, model setting, or tuning term means
- move slower and more intentionally through the implementation
Do not use this skill to replace agent-build-orchestrator or the chosen stack skill.
Read First
./references/teaching-rules.md./references/explanation-checklist.md../architecture-diagram-generator/SKILL.md (Architecture Diagram Skill)
Workflow
Phase 1: Architecture Review (MANDATORY - Do This First)
Before writing ANY code, use the Architecture Diagram Skill to generate a visual architecture:
- Discuss with the user what they want to build
- Use the
architecture-diagram-generator skill to create an architecture diagram showing:
- All major components (frontend, backend, databases, services)
- How components connect and communicate
- Technology choices for each component
- Data flow between components
- Security boundaries and authentication
- Present the diagram to the user for review and iteration
- Only proceed to implementation after the user approves the architecture
Phase 2: Implementation with Teaching
- Keep the normal build lane responsible for architecture and implementation choices.
- Before writing each meaningful code slice, explain what is about to be built and why it comes next.
- Write one manageable section at a time instead of dumping a huge implementation at once.
- After each slice, explain what changed, what the important variables or functions do, and what the user should understand before the next slice.
- Define jargon in plain English the first time it appears.
- Clarify model tuning, output tuning, retrieval tuning, and runtime choices in practical product terms rather than abstract theory.
- Include short code snippets or cited code examples from the relevant implementation when they help the user understand the concept.
- When a meaningful behavior changed, show a concise before/after snippet if it clarifies the tradeoff.
- Keep explanations supportive and specific, not patronizing or vague.
Phase 3: Function Review
When reviewing a specific function or code section:
- Reference the overall architecture diagram to show where this function fits
- Generate a focused diagram if the function has complex internal components or interactions
- Explain how the function integrates with adjacent components
Guardrails
- Do not skip the real build workflow; teaching mode rides on top of it.
- Do not overwhelm the user with giant lectures between tiny code changes.
- Do not assume the user knows jargon such as
checkpoint, handoff, tool schema, RRF, LTR, guardrail, or durable execution.
- Prefer a short explanation before code, a focused explanation after code, and a clear next step.
- Prefer small, relevant snippets over long file dumps. Cite real file paths and line numbers when possible.
- Code examples may be from newly changed code, existing related code, or intentionally simplified examples that demonstrate the current concept.
Output Contract
Each step should leave the user with:
- what we are building now
- why it matters
- what the code means
- what the important variables or settings do
- a short code example or cited snippet when it helps the concept land
- what comes next
