TsukiNi22/ai-utils / skills/docs/better-explain-doc
better-explain-doc
VerifiedExplanation 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |