Explain This
Understanding is the bottleneck, not information. This skill turns any digital
artifact into an explanation the user can genuinely absorb — shaped to how they
learn, checked by quizzes that prevent false confidence, and retained through
spaced-repetition review. The goal is formation, not summarization: who the
user becomes by understanding, not just what they can skim.
State contract
All user state lives in EXPLAIN_THIS_HOME (default ~/.explain-this/) —
never in this skill's install directory, so it survives skill updates and is
shared across agent hosts:
~/.explain-this/
LEARNER.md # who this person is as a learner — read before EVERY explanation
memory/cards.jsonl # spaced-repetition cards + SM-2 scheduling state
memory/signals.jsonl # append-only quiz-attempt evidence
First run
If ~/.explain-this/LEARNER.md does not exist, do NOT explain anything yet.
Run the interview in references/interview.md (~10 minutes), draft LEARNER.md
from references/learner-template.md, show it to the user, and apply their
corrections. The profile is the product's first artifact.
Every explanation follows the spine
Read LEARNER.md first, then build the explanation in this order:
- Why does this exist? — the problem the artifact answers. Context before content.
- The one idea — the single sentence worth retaining above all others.
- How it works — intuition before mechanism, prose-ordered (literate
sequencing), analogies drawn from the learner's deep domains, skipping what
their profile says they already know.
- What can you now do — point at the learner's formation goals: what can
they build, argue, or decide that they couldn't before.
- Check yourself — the quiz. Generate per
references/quiz.md; add each
question to the card deck per references/review.md.
Depth dial
Default comes from LEARNER.md frontmatter; per-request override phrases win:
Artifact adapters
Pick the adapter for the artifact type; it defines ingestion and what
"meaning" means for that type:
- Papers / PDFs →
references/adapters/paper.md
- Articles / markdown / essays →
references/adapters/article.md
- Code, diffs, repos →
references/adapters/code.md
Output destinations
Markdown is canonical. The user directs the destination ("put it in Obsidian",
"give me an HTML file", "just tell me here"); the default lives in LEARNER.md
frontmatter. In document output, embed quiz questions at section ends with
answers in <details> blocks. An HTML render is an optional layer for
interactive quiz widgets — never required.
Review mode
"quiz me" / "review my cards" / "explain-this review" → run the conversational
review loop in references/review.md (due cards via scripts/sm2.ts due).
When invoked for a NEW explanation while cards are due, mention it once
("6 cards due — review first, or after?") but never block.
Gotchas
- Never skip the profile read. An explanation not shaped by LEARNER.md is
a generic summary — the exact thing this skill exists to avoid.
- A summary is not an explanation. If the output could have been produced
without the artifact's actual content or without the profile, start over.
- Never write LEARNER.md's Known Weak Patterns from a single session. Only
the evidence loop (
references/review.md, thresholds) may add entries, and
every entry must cite its evidence. One bad quiz is noise, not identity.
- Quiz questions come from the artifact, not the explanation — otherwise
they're echo questions that test short-term verbal memory. See
references/quiz.md two-pass procedure.
- Grade the user's free-text answers yourself (hit/partial/miss). Never
ask them to self-grade; self-grading is generous and corrupts the evidence.
- You wrote the explanation AND grade the quiz — watch for grading
inflation. Grade against the artifact and the stored answer/rubric, not
against your own explanation's wording. When unsure between hit and
partial, choose partial.
- State is sacred. Never reset, rewrite, or prune
~/.explain-this/
except through the documented flows. Losing a learner's history is the worst
failure this tool can have.