better-explain-doc
Skill1 starsChanged 3 days agoMITView on GitHub
Explanation pages (Simple | Technical in one page, analogies vs exact terms, step-by-step animated steppers, formulas, playgrounds, quizzes, glossary) written as pages of a better-html-doc site - Markdown with :::simple / :::technical blocks (tldr summary highlighted), the level switch in the top bar next to the search, the explain-doc components (stepper, formula, playground, dfn, compare, quiz) through :::html, found by the site search, linked by the sidebar and previous / next, responsive. Use whenever the user wants an explanation, a tutorial for understanding or "une explication simple et une technique" inside a documentation site in the claude-cluster style (better-html-doc); a standalone explanation page in the older style: explain-doc.
In this repository70 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-at-endSkill
- clarifySkill
- continue-workSkill
- exportSkill
- full-permissionSkill
- ideationSkill
- interactive-questionsSkill
- onboardSkill
- pauseSkill
- presentationSkill
- rtkSkill
- setup-contextSkill
- write-like-meSkill
- audit-bugsSkill
- audit-depsSkill
- audit-qualitySkill
- audit-securitySkill
- benchmarkSkill
- cmake-styleSkill
- cpp-classSkill
- cpp-commentsSkill
- cpp-projectSkill
- cpp-styleSkill
- better-html-docSkill
- better-html-styleSkill
- better-protocol-docSkill
- docs-updateSkill
- explain-docSkill
- html-docSkill
- html-styleSkill
- protocol-docSkill
- readme-styleSkill
- reportSkill
- wiki-styleSkill
- ci-cdSkill
- git-commitSkill
- git-conventionsSkill
- pre-commitSkill
- legal-checkSkill
- legal-setupSkill
- licenseSkill
- libutils-exceptionSkill
- libutils-installSkill
- libutils-setupSkill
- libutilsSkill
- python-classSkill
- python-commentsSkill
- python-projectSkill
- python-styleSkill
- auditSkill
- cppSkill
- devSkill
- docSkill
- gitSkill
- legalSkill
- pythonSkill
- setup-projectSkill
- styleSkill
- setup-studioSkill
- The first 60 shown.
The file
Files
Explanation pages in a better-html-doc site
SKILL_DIR = directory of this file. The content rules are those of explain-doc (../explain-doc/SKILL.md: the two
levels, the 8 sections, readable steps, accuracy - every number computed, never from memory): load it first. This skill
only changes where the page lives: a page of a better-html-doc site (../better-html-doc), written in Markdown, with
the components of explain-doc (explain.css / explain.js, loaded only on these pages by the built-in explain kind).
1. Ask (AskUserQuestion, French) unless known
- Niveau par défaut :
Simple (Recommandé)·Technique. - The site, its languages and its sections come from its
site.toml(no site yet: create it withbetter-html-docfirst, aConceptssection for the explanations).
2. Write the page
src/pages/concepts/<slug>.<lang>.md - start from SKILL_DIR/templates/pages/concepts/how-caching-works.*.md:
+++
title = "How the cache works"
summary = "Why a second run is fast, explained simply or technically."
section = "concepts"
kind = "explain"
level = "simple" # the level shown at the first visit (the reader's choice is kept after)
+++
:::simple tldr
**In one sentence:** ...
:::
:::technical tldr
**Definition:** ...
:::
## The idea {#idea}
:::simple
analogy, plain words
:::
:::technical
model, vocabulary, comparison
::::::simple/:::technical= shown at that level only; text outside them is shown at both levels (diagrams, playgrounds, tables that fit both). A###inside a level block belongs to that level.- The
explain-doccomponents go in:::htmlblocks, unchanged: stepper (figure.stepper+ol.captions+svgwithdata-show/data-hl/data-at), formula (div.formula+ MathML), playground (div.playground+ a page script callingexplain.play),dfn data-def,div.compare,details.quiz. Arrows bydata-from/data-to(computed). - Bilingual site: each language file has its own copy of the figures - give their ids a language prefix (
en-q,fr-q) so they stay unique on the page. - Sections in the order of
explain-doc§3 (the idea, how it works, how fast, try it, worked example, pitfalls, check yourself, glossary and sources), 6-9 of them.
3. Build and check
The commands of better-html-doc (build_site.py, check_site.py, test_search.js), check_render.py of html-style on the built
page (0 error: both levels, both languages, both themes), then look at the page: the stepper played to its end, a playground
moved, at 1280 and 390 px, light and dark. The level switch sits in the top bar (?level=technical in a link opens that level; the
choice is shared with the other explanation pages of the site); under 640px the search takes a row under the bar, under 400px a
bilingual page gives the place of the logo to the two switches.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

