creating-explainers

Name: creating-explainers
Author: analyticalmonk

15stars1forks

How to install creating-explainers?

analyticalmonk/explain-this/creating-explainers

$npx -y skills add analyticalmonk/explain-this --skill creating-explainers

Installs into the current project.

Summary

Use when creating an interactive explainer - a single self-contained HTML page with hand-built Canvas figures. Handles source-file explainers, topic-driven research explainers, and mixed intake where files provide the spine and research adds support. Trigger phrases include "make

Files · 1

View on GitHub

SKILL.md

1	# Creating Explainers
2
3	## Overview
4
5	This skill produces a single self-contained interactive explainer in the style of distill.pub - serif typography, a sticky two-column layout, and hand-built Canvas figures the reader can interact with. The output is one `index.html` file that opens directly in a browser; no parent project, no build step, no shared infrastructure required.
6
7	Core constraints (non-negotiable):
8
9	- Zero dependencies. No npm, no bundler, no React, no D3, no Three.js, no Tailwind. Vanilla HTML + inline CSS + vanilla JS only.
10	- One file per article. All CSS in a single `<style>` block in `<head>`; all JS at the bottom of `<body>`. The only external network requests are Google Fonts.
11	- Hand-coded Canvas figures, not SVG libraries or images. 3D uses custom projection + z-sorting + lighting (see `references/figure-archetypes.md`).
12	- The voice matters as much as the visuals. Conversational, second-person, analogy-rich. Read `references/voice-and-style.md` before drafting prose.
13
14	If you find yourself reaching for a framework or asking "should I just use React for this", stop. The constraint is the point.
15
16	## When to Use
17
18	Use whenever the user asks to:
19	- Turn a paper, blog post, transcript, or research report into a walkthrough
20	- Build a distill-style or interactive explainer on any topic
21	- "Explain X" with figures the reader can interact with
22
23	Don't use for:
24	- Static blog posts with no interactivity (just write HTML)
25	- Slide decks or presentations
26	- Documentation sites or landing pages
27	- Anything that needs a build step or framework
28	- Explaining a codebase or source files - use `explaining-codebases`
29
30	## Intake: Gather Your Source Material
31
32	Intake is one phase: gather what the article is built from. The material can be given files, web research, or both. Pick the references that apply and read them when you reach this phase, not upfront.
33
34	\| You have \| Read \| Source of truth \|
35	\|----------\|------\|-----------------\|
36	\| Files (paper, URL, paste, transcript, report) \| `references/intake-from-files.md` \| The provided document(s) \|
37	\| Only a topic \| `references/intake-from-research.md` \| Web research, then synthesis \|
38	\| Files and a topic that needs more \| both \| Files as spine, research as supporting \|
39
40	Mixed intake. When the user provides files and the topic also needs material the files do not cover (recent developments, criticisms, corroboration), read both references and combine them via spine-vs-supporting. Synthesize across everything into one outline and one article.
41
42	If you only have a topic and web search is unavailable, ask the user to paste sources. Do not write a technical interactive explainer from training data alone.
43
44	## Workflow
45
46	The interactive explainer is too rich to one-shot. Work in stages and check in with the user.
47
48	```
49	1. Intake -> gather material (files, research, or both)
50	2. Research-time fact-check -> if you researched, verify sources before drafting (REQUIRED)
51	3. Outline -> propose sections + figure list, get user approval
52	4. Scaffold -> copy template, fill metadata
53	5. Prose pass -> write all sections with figure placeholders
54	6. Figures pass -> implement each interactive figure
55	7. Post-draft fact-check -> audit every claim against its source (REQUIRED, blocking)
56	8. Polish -> run the Quality Checklist to completion
57	```
58
59	Pause for user approval after the outline (step 3). This is the highest-leverage check-in - if the outline is wrong, everything after it is wasted work. Show the user: title, subtitle, section list with one-line summaries, and a numbered figure list with what each figure shows and how the reader interacts with it.
60
61	Steps 2 and 7 are gates, not suggestions. Use `fact-checking-explainers`. The interactive explainer is not done until the post-draft fact-check returns zero unresolved claims - every checkable claim is supported. See the Quality Checklist.
62
63	Step 8 is complete only when every Quality Checklist item passes. Fix any failing item before delivery.
64
65	Don't pause between the other steps unless something is genuinely ambiguous. Show progress, don't ask for permission to keep working.
66
67	## The Article Skeleton
68
69	Every article has the same skeleton. Use `assets/article-template.html` as the starting point - copy it to the output path and fill in the marked `{{PLACEHOLDERS}}`. Don't try to rebuild this structure from sc

People who liked this also viewed

6 picks

Type

creating-explainers

15stars1forks

View on GitHub

How to install creating-explainers?

analyticalmonk/explain-this/creating-explainers

$npx -y skills add analyticalmonk/explain-this --skill creating-explainers

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Creating Explainers
2
3	## Overview
4
5	This skill produces a single self-contained interactive explainer in the style of distill.pub - serif typography, a sticky two-column layout, and hand-built Canvas figures the reader can interact with. The output is one `index.html` file that opens directly in a browser; no parent project, no build step, no shared infrastructure required.
6
7	Core constraints (non-negotiable):
8
9	- Zero dependencies. No npm, no bundler, no React, no D3, no Three.js, no Tailwind. Vanilla HTML + inline CSS + vanilla JS only.
10	- One file per article. All CSS in a single `<style>` block in `<head>`; all JS at the bottom of `<body>`. The only external network requests are Google Fonts.
11	- Hand-coded Canvas figures, not SVG libraries or images. 3D uses custom projection + z-sorting + lighting (see `references/figure-archetypes.md`).
12	- The voice matters as much as the visuals. Conversational, second-person, analogy-rich. Read `references/voice-and-style.md` before drafting prose.
13
14	If you find yourself reaching for a framework or asking "should I just use React for this", stop. The constraint is the point.
15
16	## When to Use
17
18	Use whenever the user asks to:
19	- Turn a paper, blog post, transcript, or research report into a walkthrough
20	- Build a distill-style or interactive explainer on any topic
21	- "Explain X" with figures the reader can interact with
22
23	Don't use for:
24	- Static blog posts with no interactivity (just write HTML)
25	- Slide decks or presentations
26	- Documentation sites or landing pages
27	- Anything that needs a build step or framework
28	- Explaining a codebase or source files - use `explaining-codebases`
29
30	## Intake: Gather Your Source Material
31
32	Intake is one phase: gather what the article is built from. The material can be given files, web research, or both. Pick the references that apply and read them when you reach this phase, not upfront.
33
34	\| You have \| Read \| Source of truth \|
35	\|----------\|------\|-----------------\|
36	\| Files (paper, URL, paste, transcript, report) \| `references/intake-from-files.md` \| The provided document(s) \|
37	\| Only a topic \| `references/intake-from-research.md` \| Web research, then synthesis \|
38	\| Files and a topic that needs more \| both \| Files as spine, research as supporting \|
39
40	Mixed intake. When the user provides files and the topic also needs material the files do not cover (recent developments, criticisms, corroboration), read both references and combine them via spine-vs-supporting. Synthesize across everything into one outline and one article.
41
42	If you only have a topic and web search is unavailable, ask the user to paste sources. Do not write a technical interactive explainer from training data alone.
43
44	## Workflow
45
46	The interactive explainer is too rich to one-shot. Work in stages and check in with the user.
47
48	```
49	1. Intake -> gather material (files, research, or both)
50	2. Research-time fact-check -> if you researched, verify sources before drafting (REQUIRED)
51	3. Outline -> propose sections + figure list, get user approval
52	4. Scaffold -> copy template, fill metadata
53	5. Prose pass -> write all sections with figure placeholders
54	6. Figures pass -> implement each interactive figure
55	7. Post-draft fact-check -> audit every claim against its source (REQUIRED, blocking)
56	8. Polish -> run the Quality Checklist to completion
57	```
58
59	Pause for user approval after the outline (step 3). This is the highest-leverage check-in - if the outline is wrong, everything after it is wasted work. Show the user: title, subtitle, section list with one-line summaries, and a numbered figure list with what each figure shows and how the reader interacts with it.
60
61	Steps 2 and 7 are gates, not suggestions. Use `fact-checking-explainers`. The interactive explainer is not done until the post-draft fact-check returns zero unresolved claims - every checkable claim is supported. See the Quality Checklist.
62
63	Step 8 is complete only when every Quality Checklist item passes. Fix any failing item before delivery.
64
65	Don't pause between the other steps unless something is genuinely ambiguous. Show progress, don't ask for permission to keep working.
66
67	## The Article Skeleton
68
69	Every article has the same skeleton. Use `assets/article-template.html` as the starting point - copy it to the output path and fill in the marked `{{PLACEHOLDERS}}`. Don't try to rebuild this structure from sc

People who liked this also viewed

6 picks

Type