explain-this CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

This is a Claude Code and Codex plugin package with three skills that produce single self-contained interactive HTML explainer pages in the style of distill.pub. The repo root holds .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and .codex-plugin/plugin.json; each skill lives at skills/<name>/SKILL.md plus its references/ (and assets/ for the hub). That layout also satisfies the universal skills/<name>/SKILL.md convention, so the same checkout loads as plain skills in Codex, Cursor, Gemini CLI, OpenClaw, etc., and installs via the skills.sh CLI (npx skills add analyticalmonk/explain-this). Keep the skill folders flat at skills/<name>/ - that flat layout is what the skills.sh CLI walks for discovery. There is no source code to build, no test suite, no lint config.

The output of each skill is a generic standalone HTML file. The skills do not assume any parent project, multi-article index, or shared infrastructure.

The three skills and how they relate

• creating-explainers is the hub. It owns the output format (the HTML template, figure archetypes, voice, color palettes) and the intake -> outline -> scaffold -> prose -> figures -> fact-check -> polish workflow. It handles file intake, research intake, and the mix of both.
• explaining-codebases extends the hub for code. It adds code intake and code-specific figures, and defers to creating-explainers for everything about the output.
• fact-checking-explainers is the gate both must pass before delivery. It is discipline-enforcing: no explainer ships with an unverified factual claim.

Skills cross-reference each other by name (fact-checking-explainers), never with @-includes (which force-load files and burn context).

Editing these skills

• skills/<name>/SKILL.md - workflow, constraints, when-to-use rules. The frontmatter description is what triggers the skill, so be precise when editing it. Keep descriptions to when-to-use, not a workflow summary.
• skills/*/references/*.md - lazy-loaded deep references. The SKILL.md files tell Claude to read these only when relevant, so the skills stay light on context. Keep that property: don't inline reference content into a SKILL.md, and don't cross-link references in ways that force-load extras.
• skills/creating-explainers/assets/article-template.html - the canonical article skeleton with {{PLACEHOLDERS}}. Structural invariants (DPR-aware initCanvas(), sidebar TOC scroll-tracking, 1060px and 600px responsive breakpoints) live here. If output articles keep getting a layout invariant wrong, fix the template, not the article.
• .claude-plugin/plugin.json - the plugin manifest. Bump version on releases.
• .claude-plugin/marketplace.json - the marketplace entry. Keep its skills list and description in sync with the actual skills and with plugin.json.
• .codex-plugin/plugin.json - the Codex plugin manifest. Keep its skills, version, description, and interface metadata in sync with the Claude plugin metadata and README.
• skills/<name>/agents/openai.yaml - Codex UI metadata for each skill. Keep display names, short descriptions, and default prompts aligned with the matching SKILL.md.