feat(education): add explain skill — one-shot plain-language altitude drop with teach handoff

[kyle-sexton]

Summary

Adds /education:explain, a one-shot plain-language sibling to the multi-session education:teach coach (issue #303, design locked in triage 2026-07-17). Where teach coaches across sessions with persistent state, explain does a single altitude drop: it explains the given thing — a concept, code, an error, an architecture, or the assistant's own previous output — in genuinely plain words (concrete analogy, zero jargon), then layers altitude back up only on request (high-school, then peer level).

Key behaviors from the locked design:

• Anaphora default — an empty argument targets the previous assistant response, so "I don't get it" needs no topic named.
• Model auto-invocation — unlike teach (disable-model-invocation: true), explain enables auto-invoke and carries the colloquial triggers ('I don't get it', 'what does this actually do/mean', 'explain simply', 'ELI5', 'rephrase that') so those phrases reach it without a named command. Explicit /education:explain stays the guaranteed path.
• Feynman gap check — when the jargon can't be shed, that's a detected understanding gap, surfaced honestly rather than papered over with a confident restatement.
• Handoff — closes by offering /education:teach topic <x> for a multi-session deeper dive (first-party sibling, same plugin).
• Tone anchor / method — Michael Scott's "Why don't you explain this to me like I'm five" (The Office US, S5E9 "The Surplus") for tone; the Feynman technique for method (the shaky Einstein "explain it simply" attribution is deliberately cited as Feynman methodology instead). Both citations verified at build time.

Fix

• New skill plugins/education/skills/explain/SKILL.md (109 lines) implementing the locked design, matching teach's frontmatter/structure conventions but enabling model auto-invocation.
• plugins/education/skills/explain/evals/evals.json — 6 evals (anaphora default, plain-first pass, altitude-on-request, Feynman gap check, teach handoff, auto-invocation) following teach's eval schema.
• Bumped education 0.3.1 → 0.4.0 with a top-inserted CHANGELOG.md entry.
• Updated the plugin description (plugin.json) and plugins/education/README.md to cover the new sibling; added explain/eli5 keywords to plugin.json and marketplace tags.
• Regenerated the root README.md catalog block for the updated description (node scripts/generate-catalog.mjs).

Disambiguation note: education:teach already has an explain action (writes a lesson into an active learning workspace). It is namespace-distinct from this standalone /education:explain skill; the SKILL.md calls this out, and only the new skill auto-fires on "I don't get it" since teach disables model invocation.

Verification

All commands run in the worktree against origin/main.

Skill-quality gate (scripts/check-changed-skills.sh origin/main):

=== plugins/education/skills/explain ===
INFO: description length 643/1536 chars
INFO: no origin/main version (new skill) — keyword-preservation check skipped
INFO: SKILL.md 109/500 lines
INFO: markdownlint check skipped (CHECK_SKILL_SKIP_MARKDOWNLINT=1)
INFO: no metadata.category in frontmatter (optional — category not machine-readable)
CHECK-SKILL explain: PASS — 0 errors, 0 warning(s)
1 skill(s) checked, 0 failed.

markdownlint-cli2 (changed markdown): Summary: 0 error(s)

Catalog parity (node scripts/generate-catalog.mjs --check): Catalog is in sync with the manifests.

Changelog parity (scripts/check-changelog-parity.sh --check-bump origin/main): Every plugin whose version changed vs origin/main has a '## [<version>]' CHANGELOG.md entry.

Skill leaf-name collisions (scripts/check-skill-leaf-names.sh --check): All 8 cross-plugin skill leaf-name collisions are registered. (explain introduces no new collision.)

Plugin contracts (node scripts/validate-plugin-contracts.mjs): Plugin contracts validated: 33 setup skills and 1826 plugin files checked.

JSON parse of marketplace.json, plugin.json, evals.json: OK. evals.json validated against plugins/skill-quality/reference/evals.schema.json (only allowed keys; kebab-case name).

Closes #303

Related

• Sibling skill: plugins/education/skills/teach/SKILL.md
• Eval schema: plugins/skill-quality/reference/evals.schema.json

[claude]

Claude finished @kyle-sexton's task in 2m 8s —— View job

---

PR Review: feat(education): add explain skill

Tasks

• Gather context and understand the request
• Read changed files
• Review SKILL.md for correctness and design alignment
• Review evals.json for schema compliance
• Review plugin.json, CHANGELOG.md, README.md, marketplace.json
• Post findings

---

Summary

This is a well-executed, tightly-scoped addition. The skill design is coherent, the evals cover all five key behavioral mechanics, and the supporting files (CHANGELOG, README, plugin.json, marketplace.json) are updated consistently. The quality gate, schema validation, and catalog-parity checks all passed. One medium issue and a few nits are noted below.

---

Medium

Anaphora default has no cold-start guard

SKILL.md lines 44–48

The "Empty argument" section says: "Do not ask 'explain what?' when the conversation makes the referent obvious." That caveat acknowledges the referent might not be obvious, but the skill gives no instruction for the case where there is no prior assistant message at all (e.g., a new conversation where the user opens with "I don't get it" or the skill auto-fires on that phrase as the very first turn). In that situation there is no referent to resolve, and the skill's only guidance is implicitly "don't ask" — which would push the model toward hallucinating a referent or producing an empty/confused response.

The fix is one sentence in the "Empty argument" section: when there is no prior assistant message in the conversation, the anaphora default cannot resolve, and the skill should ask "What would you like explained?" before proceeding. None of the six evals cover this edge case either — eval #1's prompt ("I don't get it.") implicitly assumes prior context exists.

Fix this →

---

Nits

re-read wording is slightly misleading for the anaphora case

SKILL.md line 32

Step 2 says "Re-read the actual artifact this turn — the message just sent, the file, the error text, the code." For the anaphora path (prior assistant response), there's nothing to fetch or re-read as a tool call — the message is in context. The intent is "attend carefully to it," but re-read implies a Read tool call on a file. A minor rewording like "Re-examine the actual artifact this turn" avoids the implication. This is a wording nit, not a correctness defect.

Eval #6 tests only one auto-trigger phrase

evals.json line 67

The frontmatter description lists five colloquial triggers (I don't get it, what does this actually do/mean, explain simply, ELI5, rephrase that). Eval #6 exercises "wait, what does this actually do?". I don't get it is implicitly covered by eval #1, but ELI5, explain simply, and rephrase that have no auto-invocation eval. Since auto-invocation is explicitly labeled best-effort, this isn't a gap worth blocking on — just worth tracking if the eval suite expands.

CHANGELOG dates

CHANGELOG.md line 8

The ## [0.4.0] header has no release date. Keep a Changelog recommends ## [version] - YYYY-MM-DD. The prior entries [0.3.1] and [0.3.0] also omit dates, so this is consistent with the existing pattern. Noting it for completeness but no action needed unless you want to retroactively add dates.

---

Checklist

Area	Status
Frontmatter valid (name, description, argument-hint, user-invocable)	✅
disable-model-invocation absent (intentional, enables auto-invoke)	✅
Description length within limits (643/1536)	✅
Skill body ≤ 500 lines (109/500)	✅
Evals schema-valid (all 6 cases have id, prompt, kebab-case name)	✅
Evals cover all key mechanics (anaphora, plain-first, altitude, Feynman, handoff, auto-invoke)	✅
Version bump semver-correct (minor, additive) 0.3.1 → 0.4.0	✅
CHANGELOG entry matches [0.4.0] header	✅
README updated for both skills, namespace disambiguation present	✅
marketplace.json tags updated (explain, eli5 added)	✅
Teach handoff command syntax correct (/education:teach topic <x>)	✅
Collision registry clean (no new unregistered leaf-name collision)	✅
Cold-start guard for anaphora when no prior assistant message exists	⚠️ Missing

[claude]

Claude finished @kyle-sexton's task in 1m 39s —— View job

---

PR Review: feat(education): add explain skill

Tasks

• Gather context and understand the request
• Read changed files
• Review SKILL.md for correctness and design alignment
• Review evals.json for schema compliance
• Review plugin.json, CHANGELOG.md, README.md, marketplace.json
• Post findings

---

Summary

The medium finding from the prior review pass (cold-start anaphora guard) has been addressed in 1d5d8fe. Both the SKILL.md prose and a corresponding eval were added correctly. The overall implementation is sound — one minor new observation on the eval suite, the prior nits remain unchanged. Ready to merge.

---

Fixed (1d5d8fe)

Cold-start guard for anaphora — resolved

SKILL.md lines 49–52

The guard sentence was added in exactly the right place: "when there is no prior assistant message to resolve the anaphora against … do not hallucinate a referent: ask 'What would you like explained?' instead of proceeding blind." Precise, unambiguous, and correctly scoped to the cold-start condition only — the warm-path instruction (Do not ask "explain what?" when the conversation makes the referent obvious) is preserved.

evals.json eval #7

Eval #7 (cold-start-empty-argument-asks-what) covers the edge case with a correct expected_output and three well-scoped expectations. ✅

---

Minor — new observation

Eval #1 and Eval #7 share an identical prompt

evals.json lines 7 and 79

Both evals use "I don't get it." as their prompt. They are meant to test opposite scenarios (prior assistant context present vs. absent), but the prompt text alone cannot distinguish them — the eval runner needs to manage conversation history state externally to make them non-redundant. This is a limitation of the eval format, not a defect in the skill logic, and the expectations are correct. Worth noting so eval tooling authors know to treat these as scenario-dependent rather than prompt-only cases. Not a blocker.

---

Nits (unchanged from prior review)

re-read wording could imply a tool call
SKILL.md line 32 — "Re-read the actual artifact this turn" could be read as a Read tool call for the anaphora path where the prior message is already in context. "Re-examine" would be clearer. Wording nit, not a correctness issue.

Eval #6 covers only one of five colloquial triggers
evals.json line 67 — ELI5, explain simply, and rephrase that remain uncovered. Auto-invocation is best-effort, so no action needed now.

CHANGELOG entries have no dates
CHANGELOG.md line 6 — Consistent with prior entries; noting for completeness.

---

Checklist

Area	Status
Frontmatter valid (name, description, argument-hint, user-invocable)	✅
disable-model-invocation absent (intentional, enables auto-invoke)	✅
Description length within limits (643/1536)	✅
Skill body ≤ 500 lines (109/500)	✅
Evals schema-valid (all 7 cases have id, prompt, kebab-case name)	✅
Evals cover all key mechanics (anaphora, plain-first, altitude, Feynman, handoff, auto-invoke, cold-start)	✅
Version bump semver-correct (minor, additive) 0.3.1 → 0.4.0	✅
CHANGELOG entry matches [0.4.0] header	✅
README updated for both skills, namespace disambiguation present	✅
marketplace.json tags updated (explain, eli5 added)	✅
Teach handoff command syntax correct (/education:teach topic <x>)	✅
Collision registry clean (no new unregistered leaf-name collision)	✅
Cold-start guard for anaphora when no prior assistant message exists	✅ Fixed in 1d5d8fe

[kyle-sexton]

Post-green review pass complete (rule 8). Bot review confirms the medium finding (cold-start anaphora guard) is correctly fixed. One new minor observation (evals #1/#7 share identical prompt text, a limitation of the eval format not the skill logic) plus prior nits — all non-blocking.

No threads to resolve, CI fully green (18/18).

Flipping to ready for review; handing off to the babysit lane for merge.

[claude]

Claude finished @kyle-sexton's task in 1m 13s —— View job

---

PR Review: feat(education): add explain skill — Final Pass

Tasks

• Gather context and understand the request
• Read changed files for final verification
• Assess prior findings and new state
• Post final review recommendation

---

Summary

This is a clean, merge-ready PR. Three review passes have been run; the only medium finding (cold-start anaphora guard) was resolved in 1d5d8fe. All remaining items from previous passes are minor/nits and carry forward unchanged — none block merging.

---

State after 1d5d8fe

SKILL.md (113 lines) — frontmatter, body, and all sections are consistent with the locked design. The cold-start guard at lines 48–52 is precise and correctly scoped: the warm-path instruction ("do not ask 'explain what?' when the conversation makes the referent obvious") is preserved intact and the guard only fires on a true cold start.

evals.json (7 evals) — all cases have id, kebab-case name, prompt, expected_output, files, and expectations. Eval #7 (cold-start-empty-argument-asks-what) adds three tight expectations for the new guard. The identical prompt text in evals #1 and #7 ("I don't get it.") is a known eval-format limitation noted in the prior pass — the expectations and expected_output for each case are correct and distinct; an eval runner handling conversation-history state externally can discriminate them.

plugin.json — version 0.4.0, description updated, explain/eli5 keywords present. ✅

CHANGELOG.md — ## [0.4.0] entry is accurate and top-inserted. No date (consistent with all prior entries). ✅

---

Carry-forward nits (non-blocking, no action needed)

• SKILL.md line 32 — "Re-read the actual artifact this turn" could be read as implying a tool call for the anaphora path; "Re-examine" would be cleaner. Wording only.
• evals.json line 67 — ELI5, explain simply, and rephrase that colloquial triggers lack dedicated auto-invocation evals. Auto-invocation is best-effort; not blocking.
• CHANGELOG.md line 6 — no release date; consistent with existing entries.

---

Checklist

Area	Status
Frontmatter valid (name, description, argument-hint, user-invocable)	✅
disable-model-invocation absent — auto-invoke intentionally enabled	✅
Description length within limits (643/1536)	✅
Skill body ≤ 500 lines (113/500)	✅
Evals schema-valid (all 7 cases, kebab-case names)	✅
Evals cover all key mechanics (anaphora, plain-first, altitude, Feynman, handoff, auto-invoke, cold-start)	✅
Cold-start guard present and correctly scoped	✅ Fixed in 1d5d8fe
Version bump semver-correct (minor, additive) 0.3.1 → 0.4.0	✅
CHANGELOG [0.4.0] entry present and accurate	✅
README updated, namespace disambiguation present	✅
marketplace.json tags updated (explain, eli5 added)	✅
Teach handoff command syntax correct	✅
Collision registry clean	✅
CI green (18/18)	✅

Verdict: ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1d5d8febbd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 17s —— View job

---

PR Review: feat(education): add explain skill — Sync Pass (b3fc172)

Tasks

• Gather context and understand the request
• Check what changed with the merge sync commit
• Read current state of changed files (SKILL.md, evals.json, plugin.json)
• Assess open eval chore: initialize marketplace scaffold #1/docs(playbook): document the local plugin development loop #7 thread and any new issues
• Post findings

---

Summary

The sync commit (b3fc172) is a clean merge of origin/main — no conflicts, no regressions. The merge pulled in 0.3.2 (a doc-only license fix from another PR), which is the correct new base. All seven changed files are intact and consistent. No new issues introduced by the merge.

---

One cosmetic note from the merge

The PR description says "Bumped education 0.3.1 → 0.4.0" — but the effective diff against origin/main now shows 0.3.2 → 0.4.0, because 0.3.2 landed on main after the branch was created. The CHANGELOG and plugin.json are correct (0.4.0 is at the top, above the 0.3.2 entry); 0.4.0 > 0.3.2 is valid semver. The discrepancy is only in the PR description body, which is cosmetically stale but not a code defect.

---

Open thread — eval #1/#7 identical prompt (unchanged status: non-blocking)

The Codex review (P2) and the author's inline response confirm this accurately: both evals use "I don't get it." as their prompt and demand contradictory behaviour under the fresh-session eval recipe (docs/MIGRATION-PLAYBOOK.md:351). In a cold-start session, eval #1's expected_output ("re-read the prior message, do not ask 'explain what?'") will always fail because there is no prior message to resolve. Eval #7 is the only case that's runnable as a standalone prompt-pasted eval.

The warm-path anaphora path has no mechanically exercisable eval in the current schema (no history-fixture field). This is a schema gap rather than a skill defect; eval tooling authors need to inject conversation history externally to discriminate the two cases. Classification remains: known non-blocking, schema-level limitation, not owned by this PR.

If this eval suite is ever extended, adding a history fixture field to the schema would be the right fix; that work belongs in skill-quality, not here.

---

Carry-forward nits (unchanged, non-blocking)

• SKILL.md line 32 — "Re-read the actual artifact this turn" could imply a Read tool call on the anaphora path; "Re-examine" would be cleaner. Wording only.
• evals.json line 67 — ELI5, explain simply, and rephrase that colloquial triggers lack dedicated auto-invocation evals. Auto-invocation is best-effort; no action needed.
• CHANGELOG.md line 6 — no release dates; consistent with all prior entries.

---

Checklist

Area	Status
Merge clean — no conflicts, no regressions	✅
Frontmatter valid (name, description, argument-hint, user-invocable)	✅
disable-model-invocation absent — auto-invoke intentionally enabled	✅
Description length within limits (643/1536)	✅
Skill body ≤ 500 lines (113/500)	✅
Evals schema-valid (all 7 cases, kebab-case names)	✅
Evals cover all key mechanics (anaphora, plain-first, altitude, Feynman, handoff, auto-invoke, cold-start)	✅
Cold-start guard present and correctly scoped	✅ Fixed in 1d5d8fe
Version bump semver-correct: 0.3.2 → 0.4.0 (minor, additive)	✅
CHANGELOG [0.4.0] entry present and accurate	✅
README updated, namespace disambiguation present	✅
marketplace.json tags updated (explain, eli5 added)	✅
Teach handoff command syntax correct	✅
Collision registry clean	✅
Eval #1/#7 identical-prompt issue	⚠️ Known schema limitation, non-blocking — author confirmed

Verdict: ready to merge. No new issues from the sync; all prior findings carry forward at non-blocking status.

[claude]

Claude finished @kyle-sexton's task in 1m 45s —— View job

---

Security Review: feat(education): add explain skill

Tasks

• Gather context and understand the request
• Fetch PR diff
• Read changed files
• Analyze for security vulnerabilities
• Post findings

---

No security issues found.

Scope reviewed: All 7 changed files — marketplace.json, README.md, plugin.json, CHANGELOG.md, plugins/education/README.md, SKILL.md (new), evals/evals.json (new).

---

Analysis

This PR adds a skill definition (prompt instructions for Claude), evaluation fixtures, and documentation. There is no executable code, no GitHub Actions workflow modification, no dependency change, and no permission escalation in plugin.json.

The surface areas checked and their disposition:

plugin.json — version bump and keyword additions only. No new capability grants, no permission fields, no MCP server references, no remote execution. permalink

Auto-invocation (no disable-model-invocation) — the skill fires on colloquial triggers ("I don't get it", "ELI5", "rephrase that"). The skill's only action is generating an explanatory text response. It writes no files, executes no shell commands, and calls no APIs autonomously. No meaningful attack surface added beyond what an explicit /education:explain invocation would expose.

"fetch a primary source" grounding instruction (SKILL.md line 33) — instructs Claude to use WebFetch when explaining external concepts rather than relying on parametric memory. This follows the same grounding doctrine as the existing teach skill; it does not introduce new fetch surfaces beyond what that skill already permits. Any actual fetch still routes through the consumer's existing tool-approval controls.

Anaphora default (empty argument = prior assistant message) — Claude re-reads its own prior output to find what the user didn't follow. The theoretical indirect-prompt-injection path (an adversarial payload in a prior assistant message getting re-processed) is mitigated by the skill taking no destructive or privileged action; it only produces explanatory text. This is not a novel risk relative to any other skill that operates on conversation context.

evals.json — static prompt strings for evaluation fixtures. No executable content, no network references, no secrets. permalink

marketplace.json — tag additions only (explain, eli5). No behavioral change.

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3fc172a7d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".