Skip to main content
skill CX Codex

explain · sammcj — Claude Code skill: what it does, how to install

Explains code, systems, and algorithms using terminal ASCII diagrams or standalone interactive HTML step-through pages.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill explain -a claude-code
Open on GitHub

What explain does

This skill prioritizes visual structure over long text responses. In standard terminal mode, the agent draws a vertical ASCII diagram limited to 80 columns, followed by concise technical captions. When inspecting project files, it checks the source code first and supplies direct references formatted as path:line.

Prepending the argument with html prompts the skill to generate a self-contained page inside .explain/<kebab-slug>.html with bundled CSS and JavaScript. For sequential processes or protocols, it constructs an interactive viewer with scene controls tied to arrow keys and buttons. Generated files stay uncommitted because the skill silently adds .explain/ to Git's private info/exclude file instead of editing .gitignore.

Without an integrated browser tool, the agent cannot take screenshots to test contrast or layout bugs on the initial 1200x800 screen, and it explicitly reports that visual checks were skipped.

What it helps with

  • render ASCII architecture diagrams directly inside terminal output
  • build standalone interactive HTML pages with step-by-step playback
  • inspect implementation details linked to exact path:line locations
  • keep visual documentation untracked without editing .gitignore

Example prompts for the agent

  • /explain queue processing architecture in worker.ts
  • /explain html incoming request lifecycle through middleware
  • /explain

How to install explain

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill explain -a claude-code

2Manually: put the files in place

~/.claude/skills/explain/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/explain/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about explain

How to install explain in Claude Code?

Run npx skills add sammcj/agentic-coding --skill explain -a claude-code. Alternatively, copy the skill definition directly into ~/.claude/skills/explain/SKILL.md.

What is the difference between terminal and HTML modes?

Terminal mode outputs an ASCII diagram up to 80 columns wide with numbered captions directly in the chat. The html mode writes an interactive page featuring inline SVG or Mermaid, step controls, and light/dark theme support.

Where does the skill save generated HTML pages?

Pages are saved to .explain/<kebab-slug>.html. The skill automatically appends .explain/ to $(git rev-parse --git-path info/exclude) so your Git status stays clean without touching .gitignore.

Source text

SKILL.md · Apache-2.0
---
name: explain
description: Explain a concept, system or piece of code as a diagram-first terminal answer, or as an interactive HTML page.
disable-model-invocation: true
argument-hint: "[html] <topic>"
compatibility: claude-code
metadata:
  version: 2026-10-05
---

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.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Writing and docs →

explain by other authors comes first.

explain entireio This Claude Code skill explains why a piece of code exists. It traces a function, file, or line back to the session that produced it. CX Codex +1 625installs explain SerhiiKorniienko explain breaks down concepts from code, docs or articles at the depth you need: analogies for beginners, mechanisms for practitioners, or full deep-dives. CX Codex +1 ★ 164repo stars explain Insilico-org A Claude Code skill for turning research findings into competing, testable explanations. It activates when plsi research next selects explain. CX Codex +1 ★ 93repo stars explain TakaGoto The explain skill teaches RAG concepts, from plain-language intuition to code and practical trade-offs. Use it to dig into topics such as embeddings, chunking, or hybrid search. CX Codex +1 ★ 30repo stars pretty-mermaid imxv pretty-mermaid renders Mermaid diagrams to SVG, PNG, or ASCII/Unicode without a browser. Useful for docs, READMEs, and terminal output. CX Codex +1 4,700installs mermaid-studio Felipe Rodrigues - github.com/felipfr mermaid-studio — a skill that builds Mermaid diagrams, validates syntax and renders to SVG, PNG or ASCII. Useful when you need to document architecture or a database schema. CX Codex +1 344installs Agentic Mermaid adewale Agentic Mermaid renders Mermaid diagrams into SVG, PNG, or terminal ASCII while giving coding agents structured tools to mutate nodes safely. CX Codex +1 ★ 72repo stars diagram-design cathrynlavery diagram-design is a Claude Code skill that builds editorial diagrams as standalone HTML files with inline SVG. It covers 51 visual types under a project-specific style guide. CX Codex +1 30,900installs dashmotion csthink dashmotion generates dark-themed animated SVG diagrams as standalone HTML files. Useful for showing architecture and workflows with moving request dots and pulsing connectors. CX Codex +1 ★ 205repo stars beautiful-mermaid intellectronica Renders Mermaid diagrams into SVG and PNG formats using the Beautiful Mermaid library. Useful when the agent needs visual architecture diagrams, workflows, or data models. CX Codex +1 1,900installs

From the same set73

The whole set →
openspeccer openspeccer opens a read-only local dashboard for an OpenSpec repository and reports active changes, artifacts, and tasks. Useful when you need project status. CX Codex +1 ★ 173repo stars json-schema-lookup json-schema-lookup — a skill that points Claude at the SchemaStore catalog so it can validate config files and look up allowed options. CX Codex +1 ★ 173repo stars deferred-task-execution deferred-task-execution delays command execution in Claude Code for a specific duration or until a chosen time. Handy when builds or scripts need to wait. CX Codex +1 ★ 173repo stars compression-editor compression-editor is a Claude Code subagent that shortens prose, instructions, skills, and docs without losing meaning. It skips source code and summarisation. CX Codex ★ 173repo stars openspec-bootstrap openspec-bootstrap sets up OpenSpec in a repository by preparing its schema and config. Use it for a first-time setup or edits to openspec/config.yaml. CX Codex +1 ★ 173repo stars self-review self-review — a skill that critically reviews your recent changes and fixes what it finds. Small edits it handles itself; larger ones go to a sub-agent. CX Codex +1 ★ 173repo stars writing-fragments The writing-fragments skill interviews you about a writing topic and saves promising bits in one Markdown file. Use it to gather ideas before deciding how an article should be structured. CX Codex +1 ★ 173repo stars code-simplification code-simplification is a Claude Code skill that spots hard-to-follow code and suggests refactors. It comes into play during code review or when reducing unnecessary abstractions. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open