agentleFS
Sign inStart free
sammcjsammcj/agentic-coding/Skills/explain/SKILL.md

explain

Skill167 starsChanged 10 days agoApache-2.0View on GitHub

Explain a concept, system or piece of code as a diagram-first terminal answer, or as an interactive HTML page.

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 98 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow it with numbered captions that use the diagram's labels.

    line 23
  2. Distinctive:

    Create a task per step below, then work them to completion.

    line 27
  3. Very specific:

    Write one self-contained page to .explain/<kebab-slug>.html in the working directory: inline CSS and JS, no build step.

    line 29
  4. Distinctive:

    Put the key picture in the first 1200x800 screen.

    line 30
  5. Distinctive:

    Add other controls (sliders, toggles, compare views) only where changing a value teaches something.

    line 33
  6. Distinctive:

    If a browser tool is available, screenshot the first 1200x800 screen in light and dark, and read the console.

    line 35

“Common” is measured: kept by at least 6 in 10 of the 98 edited versions of this file we could read. “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

Arguments: $ARGUMENTS. If the first word is html use HTML mode, unless otherwise instructed use terminal mode. The rest is the topic. With no topic, explain what the conversation is currently about.

Both modes

  • Show the real mechanism: the actual components, data flow and state changes, with real names, shapes and numbers. A labelled box saying "processing" explains nothing.
  • Picture first, prose second. Prose is short captions keyed to the picture.
  • Captions follow Simplified Technical English: max 20 words per step, 25 per description, active voice, one idea per sentence, plain words with one meaning. Keep code and identifiers verbatim.
  • For code in the current project, read it first and cite path:line.

Terminal mode

  1. Draw an ASCII diagram, at most 80 columns wide. Stack vertically rather than in one long row.
  2. Follow it with numbered captions that use the diagram's labels.

HTML mode

  1. Create a task per step below, then work them to completion.
  2. Load the html-design-examples skill for visual patterns, if available.
  3. Write one self-contained page to .explain/<kebab-slug>.html in the working directory: inline CSS and JS, no build step. Reuse the slug when revising the same topic. In a git repo, append .explain/ to $(git rev-parse --git-path info/exclude) if missing, so pages stay untracked without touching .gitignore.
  4. Put the key picture in the first 1200x800 screen. Detail and depth go below it. Done when a reader gets the core idea without scrolling.
  5. Draw diagrams as inline SVG so parts can highlight and animate. For a large flowchart or sequence, Mermaid from https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.esm.min.mjs is fine.
  6. For a process (pipeline, algorithm, protocol, request lifecycle), build a step-through: scenes driven by one step index, with prev/next buttons, arrow keys and play/pause. Each scene highlights what changed and shows a one-line caption. Load on the final, fully built scene so the first screen shows the whole picture. Done when buttons, arrow keys and play/pause all move the step index.
  7. Add other controls (sliders, toggles, compare views) only where changing a value teaches something.
  8. Support light and dark via prefers-color-scheme. Text meets WCAG AA contrast.
  9. If a browser tool is available, screenshot the first 1200x800 screen in light and dark, and read the console. Fix clipped or overlapping text and any errors. With no browser tool, say the page was not visually checked.
  10. Reply with the page path and a 2-3 line summary, leaving the HTML out of the reply.

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.

Reviews can't be read right now.

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.

Check your setup, free