Research Explain Skill

Description

Generates high-quality explanations of concepts using Gemini and Codex in parallel (Phase 1: MAGI strategy exploration), then synthesizes a single-voice explanation with Claude (Phase 2: convergent generation).

Usage

/research-explain "concept" [--domain physics|ai_ml|statistics|mathematics|paper] [--audience general-public|high-school|undergraduate|phd-student|researcher|expert|"free text"] [--weights '{"clarity":0.2,"accuracy":0.2}'] [--depth low|medium|high|max] [--personas N] [--claude-only] [--substitute "Gemini -> Opus"]

Arguments

• $ARGUMENTS — The concept to explain and optional flags:
  • --domain — Knowledge domain (physics, ai_ml, statistics, mathematics, paper). Auto-inferred if omitted.
  • --audience — Target audience (default: phd-student):
    • general-public — No assumed technical background
    • high-school — Basic math/science literacy
    • undergraduate — Introductory college-level knowledge in the domain
    • phd-student — Graduate-level domain knowledge (default)
    • researcher — Active researcher familiar with the field
    • expert — Deep specialist in the exact sub-field
    • "free text" — Any custom audience description (e.g., "medical doctors learning ML")
  • --weights — JSON object of scoring weights for explanation quality ranking. Keys: clarity, accuracy, depth, accessibility, completeness, engagement. Values must sum to 1.0. If omitted, Claude analyzes the prompt and audience to recommend adaptive weights for user confirmation (see Step 0a).
  • --depth — Controls explanation pipeline depth (default: medium):
    • low — Skip Phase 1 entirely; Claude generates explanation directly
    • medium — Full MAGI (parallel brainstorm + cross-review) → explanation
    • high — MAGI + adversarial debate → explanation with misconceptions section
    • max — Hierarchical MAGI-in-MAGI: N persona subagents → meta-review + debate → multi-perspective deep dive
  • --personas N|auto — Number of explanation-specialist subagents for --depth max (default: auto, range: 2-4). When auto, Claude analyzes the concept to determine the optimal persona count. Ignored for other depth levels.
  • --claude-only — Replace all Gemini/Codex MCP calls with Claude Agent subagents. Use when external model endpoints are unavailable or for a Claude-only workflow. Two subagents with distinct cognitive styles (Creative-Divergent and Analytical-Convergent) ensure perspective diversity.
  • --substitute "Agent -> Opus" — Replace a specific MAGI agent with Claude (Opus). Accepted: "Gemini -> Opus", "Codex -> Opus". Can be specified multiple times. If both substituted, equivalent to --claude-only.

Instructions

Shared rules: Read ${CLAUDE_PLUGIN_ROOT}/shared/rules.md before starting. §MCP, §Claude-Only, §LaTeX, §Substitute apply to this skill. Inline fallback (if shared rules unavailable): Gemini models: gemini-3.1-pro-preview → gemini-2.5-pro → Claude. Codex: gpt-5.4. All math in LaTeX only (no Unicode: σ₁→$\sigma_1$). Use @filepath for MCP file refs; subagents use Read tool.

MCP Tool Rules

See §MCP in shared rules. Additionally:

• Codex: Use mcp__codex-cli__ask-codex for analysis/review.
• Visualization (if plots are generated): See §Visualization.
• When to search: concept definitions, pedagogical resources, common misconceptions, recent breakthroughs, related concepts, fact-checking claims

Claude-Only Mode

See §Claude-Only and §Substitute in shared rules. This skill uses Teacher/Critic asymmetric roles (see Step 0b).

LaTeX Formatting Rules

See §LaTeX in shared rules.

Reusable Templates

Read references/templates.md for full definitions.

When this skill is invoked, follow these steps exactly:

Step 0: Setup

1. Parse the concept to explain from $ARGUMENTS. If a --domain flag is provided, note the domain (physics, ai_ml, statistics, mathematics, paper). Otherwise, infer the domain from the concept.
2. Pipeline context detection: If an {output_dir} was provided by the calling context and .workspace.json already exists at the output root, skip directory creation and write to {output_dir}/explain/ instead of creating a new versioned directory.
3. Create the output directory: outputs/{sanitized_concept}_{YYYYMMDD}_v{N}/explain/
   • Sanitize the concept: lowercase, replace spaces with underscores, remove special characters, truncate to 50 chars.
   • Use today's date in YYYYMMDD format.
   • Version: Glob for outputs/{sanitized_concept}_{YYYYMMDD}_v*/ and set N = max existing + 1 (start at v1).
4. Write .workspace.json at the output directory root:

   {
     "output_dir": "{absolute_path}",
     "skill": "research-explain",
     "concept": "{original_concept}",
     "domain": "{domain}",
     "audience": "{audience}",
     "depth": "{depth}",
     "created_at": "{ISO-8601}"
   }
   

5. If a domain template exists at ${CLAUDE_PLUGIN_ROOT}/templates/domains/{domain}.md, read it for context.
6. Parse --audience: Accept general-public, high-school, undergraduate, phd-student, researcher, expert, or any quoted free-text string (default: phd-student). The audience propagates into every prompt, persona casting, weight defaults, and the final explanation.
7. Parse --weights:
   • If --weights is explicitly provided: Validate that keys are a subset of {clarity, accuracy, depth, accessibility, completeness, engagement} and values sum to 1.0. Save immediately to explain/weights.json with metadata:

     {
       "weights": { "<user-provided weights>" },
       "_meta": {
         "method": "explicit",
         "domain": "<detected domain>",
         "audience": "<detected audience>"
       }
     }
     

     Skip Step 0a entirely.
   • If --weights is not provided: Load the audience baseline from T1 in references/templates.md as a reference only (do not save yet — Step 0a handles saving after user confirmation).
8. Parse --depth: Accept low, medium, high, or max (default: medium).
   • low — Skip Phase 1 entirely; Claude generates explanation directly (jump to Step 2)
   • medium — Full MAGI + one-shot cross-review → strategy synthesis → explanation
   • high — Full MAGI + cross-review + adversarial debate → strategy synthesis → explanation with misconceptions
   • max — Hierarchical MAGI-in-MAGI pipeline (Steps 1-max-a through 1-max-d replace Steps 1a/1b/1b+/1c)
9. Parse --personas N|auto: Accept integer 2-4 or the string auto (default: auto). Only used when --depth max; ignored otherwise.
   • If auto: Defer persona count determination to Step 0b, where Claude analyzes the concept's complexity, number of distinct pedagogical angles, and audience needs to select the optimal N (2-4).
   • If an explicit integer is given: Use that value directly.
10. Parse --claude-only: Boolean flag (default: false). When present, all Gemini/Codex MCP calls are replaced with Claude Agent subagents. See the Claude-Only Mode section above for the replacement table and cognitive style definitions.

Step 0a: Adaptive Weight Recommendation

If --weights was explicitly provided: Skip this step entirely (weights already saved in Step 0). Full procedure: Read T2 in references/templates.md for the signal detection table, normalization rules, user confirmation flow, and weights.json save format.

When --weights is omitted: detect concept/audie