explain
Explain a concept at a specified audience tier (ELI5 / curious-undergrad / experienced-peer / domain-expert); pick the analogy and abandon it before it lies.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- explain
- description
- Explain a concept at a specified audience tier (ELI5 / curious-undergrad / experienced-peer / domain-expert); pick the analogy and abandon it before it lies.
02 资源文件 1
- 参考文档routing.yaml319 B
03 SKILL.md 正文
explain
Explanations fail when the audience tier is implicit. Pick the tier first, then the analogy, then the where-the-analogy-breaks.
Mode: generative — diverge before converging. Produce genuinely different options first (the obvious answer is one candidate, not the answer), then narrow with stated criteria.
When to use
- The user asks "explain X" or "how does Y work?".
- A workflow needs to teach a concept before a decision.
- Onboarding a new contributor on an unfamiliar area.
Inputs
- The concept (required).
- Audience tier (one of:
eli5,curious-undergrad,experienced-peer,domain-expert). If unstated, infer it from how the user writes and name the tier you chose at the top; ask only when the guess would change the answer a lot. - Optional: domain context (what the audience already knows).
Procedure
- Pin the tier. Each tier has a different contract:
- ELI5: a 5-year-old hears it and gets the vibe. Concrete objects, one analogy, no jargon. Accept that detail is lost.
- Curious undergrad: 1–2 paragraphs. One analogy, one limit of the analogy, one terminology bridge.
- Experienced peer: skip the analogy. Compare to something they already know in this domain. Cite the mechanism, not the metaphor.
- Domain expert: zero analogy. Talk about the specific thing — what's load-bearing, what's a footgun, what's commonly misunderstood.
- For ELI5 and undergrad: draft three candidate analogies from different domains (kitchen, traffic, a library, a sport, …) before choosing — the first analogy that comes to mind is usually the most worn. Pick the one whose breaking point matters least for this audience's next question, then immediately state where it breaks. An analogy that doesn't disclose its limits will mislead the learner.
- For peer and expert: pick a single reference point in their existing knowledge. "Like X but Y" beats invented metaphor.
- One concept per pass. If you need to explain a prerequisite first, stop and explain the prerequisite alone first.
Output
explain: <concept> — tier: <ELI5 | undergrad | peer | expert>
[content following the tier contract]
[For ELI5 / undergrad only] Where the analogy breaks:
- <one or two specific limits>
Quality bar
- Tier is named at the top.
- ELI5 / undergrad → analogy + its limit, chosen from three candidates in different domains (not the stock one by default).
- Peer / expert → no invented metaphor; reference existing knowledge.
- One concept per explanation. If a prerequisite is needed, surface it.
Anti-patterns to avoid
- ELI5 that slips in jargon ("it's like a hash table"). Not 5-year-old.
- Expert explanation that wastes time on prerequisites the expert already knows.
- Analogy without limits ("the kernel is like a librarian"). Misleads.
- Trying to cover multiple concepts in one explanation; the audience leaves with none.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).