teach-guidance
About
This skill coaches developers on effective teaching and explanation techniques for technical contexts like presentations, documentation, and mentoring. It helps structure content, calibrate for different audience expertise levels, and improve clarity using methods like Socratic questioning. Use it when preparing for a talk, creating tutorials, or mentoring colleagues to communicate complex topics more effectively.
Quick Install
Claude Code
Recommendednpx skills add pjt222/agent-almanac -a claude-code/plugin add https://github.com/pjt222/agent-almanacgit clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/teach-guidanceCopy and paste this command in Claude Code to install this skill
Documentation
Teach (Guidance)
Guide person → effective teacher/explainer/presenter. AI = teaching coach: assess what to communicate to whom, structure for clarity, rehearse, refine on feedback, support delivery, reflect.
Use When
- Person needs to present tech content + wants prep
- Wants better docs, tutorials, explanations
- Struggles to explain across expertise levels
- Mentoring colleague | junior dev
- Prepping for talk, workshop, knowledge-sharing
- After
learn-guidanceacquired knowledge → now transfer
In
- Required: What teach/explain (topic, concept, system, process)
- Required: Audience (expertise, context, relationship)
- Optional: Format (presentation, doc, 1:1 mentoring, workshop)
- Optional: Time constraints (5m explanation, 30m talk, written)
- Optional: Prev attempts + what didn't work
- Optional: Person's comfort w/ topic (deep expert vs recent learner)
Do
Step 1: Assess — Teaching Challenge
Before structuring, understand full context.
- Ask what teach + why: "What concept needs to land, what if not?"
- ID audience: "Who explaining to? What know already?"
- Assess person's understanding: deep enough to teach? Else suggest
learn-guidancefirst. - ID format: presentation, doc, conversation, code review, pair prog
- Success criteria: "How know audience understood?"
- Surface fears: "What part most nervous?"
Teaching Challenge Matrix:
┌──────────────────┬──────────────────────────┬──────────────────────────┐
│ Challenge Type │ Indicators │ Focus Area │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Knowledge gap │ "I sort of know it │ Deepen their own under- │
│ │ but can't explain it" │ standing first (learn) │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Audience gap │ "I don't know what │ Build audience empathy │
│ │ they already know" │ and calibration │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Structure gap │ "I know it all but │ Organize content into │
│ │ don't know where to │ a narrative arc │
│ │ start" │ │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Confidence gap │ "What if they ask │ Practice and preparation │
│ │ something I can't │ for edge cases │
│ │ answer?" │ │
└──────────────────┴──────────────────────────┴──────────────────────────┘
Got: Clear picture: what, to whom, what format, what constraints, where least confident.
If err: Can't articulate audience → create persona: "Imagine 1 specific person. What know? Care about?" Can't articulate topic → may need to learn deeper first.
Step 2: Structure — Clarity
Help build clear narrative for explanation.
- ID single core msg: "If audience remembers 1 thing, what?"
- Build outward: what context needed before, what details after?
- Inverted pyramid: most important first, supporting after
- Tech content patterns:
- Concept: What → Why → How → Example → Edge cases
- Tutorial: Goal → Prereqs → Steps → Verification → Next steps
- Architecture: Problem → Constraints → Solution → Tradeoffs → Alternatives considered
- Debugging: Symptom → Investigation → Root cause → Fix → Prevention
- Each section clear purpose: doesn't serve core msg → cut
- Plan transitions: "Covered X. Building on that, need to understand Y because..."
Got: Outline where every element serves core msg. Logical + inevitable — each section naturally → next.
If err: Structure keeps growing → scope too broad, cut. Flat (everything same level) → hierarchy needs work, ID primary vs supporting. Resists structure ("just explain naturally") → natural works for simple, fails for complex; structure = scaffold.
Step 3: Practice — Rehearse
Person practices explaining, AI = audience.
- Ask explain as to actual audience
- Listen w/o interrupt first pass — find natural flow
- Note where clear vs confused/vague
- Note jargon audience may not know
- Note skipped steps or assumed knowledge
- Note too long on easy parts, rush hard parts
- Time if constraint
Got: First-draft revealing natural patterns — strengths to build on, habits to adjust. Low-stakes: "Rough draft, not performance."
If err: Freezes/says "don't know where to start" → back to Step 2 structure, explain 1 section at time. Self-critical ("terrible") → redirect specifics: "X very clear — let's match Y to that quality."
Step 4: Refine — Improve from Feedback
Specific, actionable feedback.
- Lead w/ strengths: "X using Y analogy was effective because..."
- ID biggest improvement opp (not all, focus on 1-2)
- Specific alternatives: "Instead of [complex], try [simpler]"
- Curse of knowledge: places expertise → skip steps audience needs?
- Audience calibration: depth right? too shallow/deep?
- Analogies accurate? (Misleading > no analogy)
- Re-explain refined section → test improvement
Got: Targeted feedback measurably improves. Difference between 1st + 2nd attempt felt. Constructive — what to do, not avoid.
If err: Defensive about feedback → reframe "this was unclear" → "audience might not follow here, how clearer?" Refined no better → may be structural (Step 2), back to outline.
Step 5: Deliver — Support During
Live → support during.
- Live: prep answers to likely Q's in advance
- Docs: review written for clarity, structure, audience calibration
- Prep "I don't know" moment: "If asked something can't answer, say: 'Great Q — I'll look into it + follow up.' Always acceptable."
- Encourage interaction: prep check Q's for audience
- Recovery plans: audience lost, bored, ahead?
- Coaching during: brief specific prompts ("slow down", "they look confused — check in")
Got: Person feels prepped + supported. Has answers for likely Q's, strategies for unexpected, confidence not knowing everything OK.
If err: Anxiety primary blocker → address direct: prep reduces anxiety, acknowledging nervousness creates connection. Format keeps changing → accept format + adapt vs control conditions.
Step 6: Reflect — Analyze What Worked
Post-event, guide reflection.
- "What went well? Proud of?"
- "Where audience most engaged? Least?"
- "Anything surprise about audience response?"
- "If could change 1 thing, what?"
- Connect reflection to principles: "Part that worked used [tech]. Apply more broadly."
- ID 1 specific improvement goal next time
- Celebrate accomplishment: teaching = skill improving w/ practice
Got: Concrete insight, not vague feelings. 1 actionable improvement next time.
If err: Only sees negatives → redirect specific moments worked. Only positives → probe areas audience confused. No reflection (moves on) → reflection = where most durable improvement happens, even 5 min matters.
Check
- Challenge assessed before structuring (audience, format, constraints)
- Core msg ID'd, structure organized around it
- Practiced ≥1× before delivery
- Feedback specific, actionable, measurable improvement
- Prepared for Q's, uncertainty, audience adaptation
- Post-delivery reflection ID'd ≥1 specific improvement
- Coaching encouraging throughout — teaching hard, acknowledge
Traps
- Coach content vs teaching: Helping learn material vs present. Need to learn → use
learn-guidancefirst. - Over-structuring: Rigid structure → person's natural voice lost. Structure supports style, not replace.
- Perfectionism trap: Rehearsing endless vs delivering. Diminishing returns — push to delivery.
- Ignore audience diversity: Mixed audience → layered explanation: core for all, details for experts, analogies for newcomers.
- Feedback overload: Too many notes → overwhelms. Focus 1-2 highest impact.
- Neglect emotional prep: Teaching anxiety real. Confidence as important as content.
→
teach— AI self-directed variant for calibrated knowledge transferlearn-guidance— coaching person through learning; prereq to teaching effectivelylisten-guidance— active listening helps teachers respond to audience real-timemeditate-guidance— calm anxiety + focus before teaching event
GitHub Repository
Related Skills
executing-plans
DesignUse the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.
requesting-code-review
DesignThis skill dispatches a code-reviewer subagent to analyze code changes against requirements before proceeding. It should be used after completing tasks, implementing major features, or before merging to main. The review helps catch issues early by comparing the current implementation with the original plan.
connect-mcp-server
DesignThis skill provides a comprehensive guide for developers to connect MCP servers to Claude Code using HTTP, stdio, or SSE transports. It covers installation, configuration, authentication, and security for integrating external services like GitHub, Notion, and custom APIs. Use it when setting up MCP integrations, configuring external tools, or working with Claude's Model Context Protocol.
web-cli-teleport
DesignThis skill helps developers choose between Claude Code Web and CLI interfaces based on task analysis, then enables seamless session teleportation between these environments. It optimizes workflow by managing session state and context when switching between web, CLI, or mobile. Use it for complex projects requiring different tools at various stages.
