agentleFS
shubham0704shubham0704/claude-skills/explain-systems-visually/SKILL.md

explain-systems-visually

Skill2 starsChanged 6 months agoMITView on GitHub

Create or revise technical teaching slides and visual walkthroughs with prerequisite-aware progression, explicit inputs and outputs, stable color-linked equations and algorithm steps, and checks for understanding and recall. Use when readers must connect a system's purpose, components, mathematics, and execution.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 14 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the current source and implementation before explaining them.

    line 18
  2. Distinctive:

    Keep this contract in authoring notes, not as boilerplate on every slide.

    line 33
  3. Very specific:

    Use this compact authoring contract for each substantive reveal: question -> established prerequisites -> new move -> interpretation -> …

    line 44
  4. Distinctive:

    Keep it off the audience slide.

    line 46
  5. Distinctive:

    Read narration across slide boundaries as a continuous explanation before styling.

    line 52
  6. Distinctive:

    Use a stable overview when a system map helps.

    line 56
  7. Distinctive:

    Keep geometry, names, symbols, and role colors stable across related views.

    line 61
  8. Distinctive:

    Use the same semantic color for a step and its block.

    line 81
  9. Distinctive:

    When a governing formulation anchors the story, first show a readable compact view with an intelligible objective.

    line 100
  10. Distinctive:

    Keep decisions, objectives, hard constraints, penalties, and evaluation metrics distinct.

    line 105
  11. Distinctive:

    Put claim-limiting assumptions in the main explanation.

    line 110
  12. Distinctive:

    Use the teaching sequence to expose missing premises and unresolved scientific questions before polishing a manuscript.

    line 117
  13. Distinctive:

    Keep symbols, semantic colors, and step identities stable, while consolidating overlays and repeated recall views for print.

    line 122
  14. Very specific:

    Use rigorous-paper-author for the paper's claim and evidence structure when available.

    line 127
  15. Distinctive:

    Do not equate multiple reviewers with demonstrated audience comprehension.

    line 137
  16. Distinctive:

    Before adding a slide, try reordering, replacing abstraction with an example, recalling an earlier anchor, removing repetition, or moving …

    line 139

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Explain Systems Visually

Teach why each object is needed, what it means, and how it advances the opening question. A readable diagram and a defined symbol do not establish understanding. Preserve the overall map while revealing each operation and its consequences.

Respect the requested medium, audience, and duration. A teaching walkthrough and a short research talk need different depth; do not turn every request into a deck or add slides automatically. Retain an equation-and-text format when requested.

Establish the teaching contract

Read the current source and implementation before explaining them. Retain their notation and abstraction boundaries; identify source disagreements instead of silently combining versions. Separate supplied method, implementation choices, proposed extensions, and demonstrated results.

State the audience's starting knowledge and one question the explanation should enable them to answer. Put the intended output or decision near the beginning, before its machinery. If audience or duration is missing, state a reasonable assumption; ask only when the answer would materially change the artifact.

For each meaningful block, establish its role, input, operation, output, persistent state, initialization, and parameters. Mark quantities as supplied, measured, inferred, learned, solved, or predicted, as applicable at each phase. An observed quantity in training may be predicted during deployment. A learned function, integrator, state, and coordinate transform are different objects. Keep this contract in authoring notes, not as boilerplate on every slide.

Plan progression before layout

For a new sequence or a flow repair, read references/learning-flow.md. Check three scales:

  • Whole explanation: purpose, dependencies, method, consequence, evidence.
  • Within each section: establish the need, teach the operation, use its result.
  • Adjacent slides or reveals: the next step consumes something already understood.

Use this compact authoring contract for each substantive reveal: question -> established prerequisites -> new move -> interpretation -> next question. Keep it off the audience slide. Do not demand identical slide structures or equal amounts of text. Aim for one coherent conceptual move, not necessarily one equation.

Distinguish physical dependency order, execution order, and teaching order. Match the algorithm's overall progression where useful, but teach a prerequisite before invoking its name. Do not draw a sequential pipeline for a simultaneous solve. Read narration across slide boundaries as a continuous explanation before styling.

Preserve a visual vocabulary

Use a stable overview when a system map helps. Orient, highlight one block, expand its input-operation-output, trace a concrete case, then reconnect to the whole. For stateful systems, distinguish within-step computation, between-step state updates, and between-run learning. Show what persists or resets.

Keep geometry, names, symbols, and role colors stable across related views. Reuse semantic colors in blocks, equation terms, port labels, and relevant algorithm lines. Keep explicit labels and grayscale legibility; color reinforces identity rather than replacing it. Do not assign a new color to every variable.

Label what moves along arrows. Distinguish physical exchange, data dependency, state carry, and gradients when several coexist. Containment is not execution; equation-to-block correspondence lines are not flow arrows. Preserve port directions and distinguish known inputs from inferred or computed quantities.

For Beamer, read references/beamer.md.

Link the algorithm to its explanation

Give meaningful algorithm steps stable identifiers and link them to the block, equation, source, and explanation that implement or explain each operation. Expose the input/output contract before a compressed function call. Distinguish an explanatory pseudocode name from an actual API. Identify training, one-step prediction, rollout, and composition as separate operations when they are.

Use the same semantic color for a step and its block. On an expansion, emphasize the relevant line range; do not show the complete algorithm on every page. Keep reference identifiers stable when pagination changes. Check control flow: every consumed quantity must be available on that path, with consequential solver, initialization, loss, and stopping choices traced to the appropriate source. Familiar optimizers need less teaching than the model-specific computation.

Make the mathematics teach the operation

Introduce purpose and a concrete interpretation before relying on shorthand. Where abstraction is the obstacle, show a small explicit case before the compact map, matrix, or function name. Explain domain/codomain, units, direction, sign, and role where they matter. Define a law by what it maps, not just its title.

Separate physical evolution from inference about it, and parameter fitting from using fixed parameters. Explain constraints versus rates, values versus their derivatives, and explicit time dependence versus changing arguments when those distinctions matter. Do not impose these categories on unrelated topics.

When a governing formulation anchors the story, first show a readable compact view with an intelligible objective. Revisit it at milestones with the same equations, row positions, labels, and colors, highlighting what is now understood. Each return must enable a new answer. Secondary definitions can live in a linked expansion; omitted conditions must not silently change the problem. Keep decisions, objectives, hard constraints, penalties, and evaluation metrics distinct. Improved cost alone does not establish optimality or stability.

Show both contributing terms before demonstrating cancellation. Preserve signs, transposes, grouping, and units through styling; color is not parentheses. Put claim-limiting assumptions in the main explanation. Separate physical consistency, numerical solvability, identification, prediction accuracy, and experimental evidence. A diagram or successful solve is not a proof of all five. Label illustrative examples as such; do not manufacture supporting experiments.

When the walkthrough is a rehearsal for a paper

Use the teaching sequence to expose missing premises and unresolved scientific questions before polishing a manuscript. A storyboard can precede a full deck; reuse source-current slides rather than automatically regenerating them. Map each substantive teaching question to a paper paragraph, figure, equation, or algorithm step, with its evidence and indispensable assumptions. Keep symbols, semantic colors, and step identities stable, while consolidating overlays and repeated recall views for print. Supply in prose any bridge that previously depended on the speaker. A clear illustration is not measured evidence, and a successful explanation does not by itself demonstrate a novel contribution.

Use rigorous-paper-author for the paper's claim and evidence structure when available. A small paper edit does not require producing a separate slide deck.

Review, compress, and verify

For substantial walkthroughs, use the gates and reviewer protocol in references/review-and-testing.md. One lead author owns the integrated narrative and notation. Small changes may use separate review passes; substantial technical work benefits from independent technical and first-reader reviews when delegation is available and authorized. Do not equate multiple reviewers with demonstrated audience comprehension.

Before adding a slide, try reordering, replacing abstraction with an example, recalling an earlier anchor, removing repetition, or moving secondary detail to backup. Teach a foundation once, then retrieve it at the point of need. Preserve material assumptions and input/output contracts during compression.

Render the actual deliverable and inspect every page or reveal, including dense pages at full size and adjacent overlays in order. Check mathematical grouping, labels, arrows, clipping, and positional drift. Sweep for repeated defect classes and fix shared macros where appropriate. A clean compile, symbol checker, or phrase-presence test does not establish comprehension or visual correctness.

Deliver the requested artifact and editable source where appropriate, with speaker notes when useful. Report the checks actually performed and remaining limits; if rendering was not inspected, do not call it visually verified.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.