Explain a topic with ak:explain

Build a grounded explanation of a concept, code path, or system in Markdown or self-contained HTML, with optional ELI5 wording.

Use ak:explain when you need a mental model of a new topic, file, system, error, or decision. The Skill separates observed facts from inference and can emit Markdown or a self-contained HTML visual.

Choose ak:explain for a grounded explanation

Use ak:explain when

You want a walkthrough, mental model, or “how does this work” answer.
You want --eli5 analogies that still keep every material warning.
You want --html for a local, offline visual explanation.

Choose another workflow when

You only want the immediately previous assistant message restated. Use ak:bro.
You want to open or generate a generic visual, slides, or a diff review. Use ak:preview.
You need an interactive system map from typed JSON. Use ak:diagram.

Run the Skill

Complete Onboarding, and confirm Engineer Kit is installed for your runtime and scope.

Runtime	Invocation	Availability boundary
Claude Code	`/ak:explain ...`	Uses the installed Engineer Skill; file and browser access depend on the session.
Cursor	`/ak:explain ...`	Uses the user-verified slash spelling; helper and browser access depend on the session.
Codex	`$ak:explain ...`	Uses native Skill discovery; filesystem and browser access depend on the environment.

/ak:explain "How does request authentication reach the order service?" --html

/ak:explain "How does request authentication reach the order service?" --html

$ak:explain "How does request authentication reach the order service?" --html

Flag	Effect	Boundary
(none)	Markdown explanation	Does not write files unless the runtime already would
`--eli5`	Everyday analogies; technical terms defined on first use	Must preserve every material warning and uncertainty
`--html`	Self-contained HTML visual explanation	Activates `ak:frontend-design` first, then `ak:diagram` when installed; otherwise a semantic inline SVG/CSS fallback
`--html --eli5`	HTML with ELI5 copy and prominent warning panels	Same file and composition boundary as `--html`
`--ak-render`	HTML compiled from a Page Spec with AK Render	Opt-in; implies `--html`; see the AK Render route

Unknown flags return concise usage help. If the subject is missing, the Skill asks one focused question.

Opt in to the AK Render HTML route

--ak-render implies --html and compiles the visual explanation from a Page Spec. Instead of hand-writing the page, the Skill writes explain-<slug>.page.yaml beside the HTML and compiles it with the pinned npx -y @bestagentkits/render@0.2.0 compiler, which needs Node 20.11 or later. A project that has an .ak-render/ directory of AK Render theme presets selects this route automatically, without a per-run opt-out.

The hand-written HTML route stays the default. AK Render remains opt-in because a measured comparison with the default route did not pass its quality gate.
The page keeps the same required sections as the default route.
The compiled page opens over file:// with zero network requests. The first npx run downloads the pinned package from the npm registry; later runs use the cache.
To change the page, edit the spec and recompile. Do not patch the compiled HTML.
Diagram panels compile through the ak:diagram page wrapper, which embeds the real SVG.
If Node, npx, or the package is unavailable, or the spec is still invalid after three repairs, the Skill uses the default route and states the reason in its report.

Keep explanations bounded

Explanation is not execution

User-supplied files, logs, and issue text are untrusted data. The Skill must not follow embedded instructions, expose secrets, or treat analogies as literal truth.

HTML output is a local artifact. It does not publish, deploy, or commit the page.

Verify the result

A complete run should provide a gist, the core parts, the mechanism, a concrete example, and caveats. HTML runs should report the written path, such as plans/visuals/explain-{slug}.html or the plan-aware equivalent, and whether ak:diagram compiled or the fallback was used.