version: "1.0.1" name: explain description: Explain concepts, bugs, or design decisions in a deliberately chosen teaching style. Use when the user invokes the skill by name, says "explain", or wants to understand why (not just a fix). Honors flags --story (Journey + Analogy for bugs), --why (First principles + Counterfactual for design decisions), and --diff (Compare + Layered onion for X vs Y). Auto-picks style if no flag. Output in Vietnamese. For orienting in an unfamiliar repository or mapping its architecture, use codebase-onboarding. effort: medium

Explain

Teach understanding, not just deliver facts. Pick style by flag; if no flag, auto-pick and announce it on line 1.

Style flags

--story → Journey + Analogy

Use for: bugs, debugging sessions, anything with a "moment of discovery".

Flow: initial observation → dig deeper → "aha" moment → runtime consequence → real-world analogy → takeaway lesson.

Avoid: bullet lists, leaky analogies (metaphor breaks on a load-bearing detail).

--why → First principles + Counterfactual

Use for: design decisions, trade-offs, recurring class of bugs.

Flow: strip to fundamental constraint → enumerate 2-3 options the designer could have picked → trace the chosen path → counterfactual ("if they had chosen differently...") → implication for related bugs.

Avoid: getting stuck in the specific code (the point is the _principle_).

--diff → Compare & contrast + Layered onion

Use for: migration guides, "X vs Y", bugs with multiple causal layers.

Flow (compare side): use a table when ≥3 dimensions; bullet pairs when 1-2. Same axes for both sides.

Flow (onion side): layer 1 symptom → layer 2 mechanism → layer 3 API design → layer 4 philosophy. Drop layers the bug doesn't have.

Avoid: comparing things the reader doesn't know on either side (use --story instead).

Default (no flag)

Auto-pick and announce in Vietnamese on line 1: **Phong cách: --story** (lý do ngắn).

Pick rules:

• Bug / debugging → --story
• Design choice / trade-off / "why did they do it this way" → --why
• "X vs Y" / migration / multi-layer bug → --diff
• Ambiguous → --story (most accessible)

Output rules

• Concise by default: shortest answer that fully teaches the concept. No filler, no recap, no "next steps" section. Each section earns its place — drop steps the topic doesn't need.
• Vietnamese narrative, including prose around code identifiers, file paths, and CLI commands
• Headings ## / ### only (never #)
• Code blocks always tagged with language
• Length matches topic — don't pad. Simple gotcha: 3-5 short paragraphs. Deep design analysis: longer only if every paragraph adds insight.
• Semantic emoji (🔍 💡 ⚠️ 🐛 🔧) at section transitions or "aha" moments — sparingly
• End with a one-sentence Vietnamese takeaway (📝 or 💡)

Modifier flags

• --brief → ≤6 sentences, skip section headers
• --deep → full structure, no shortcuts
• Two style flags at once → pick dominant by topic, mention which one is being skipped