mcpField
E
explain

explain

github.com/mathbulletDocuments175174 installsUpdated 2w ago
Repository

About explain

A skill that sets conventions for writing explainer documents, from terminology and diagrams to structure and concrete examples. It is intended for authors who need explicit, carefully connected explanations.

Key features

  1. 01Term-list requirements
  2. 02Mermaid diagram conventions
  3. 03Explicit causal explanations
  4. 04Five-part document structure

Use cases

  1. 01Planning an explainer document
  2. 02Defining specialized terms consistently
  3. 03Creating diagrams with Mermaid
  4. 04Explaining mechanisms and procedures

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mathbullet/skills --skill explain

After installing, type/explainin Claude Code to confirm it loaded.

Details

From the project README

Explainer Document Conventions

Term handling

  • Put a term list at the top of the document in table form (| Term | Description |). Every specialised term used in the body must be defined in this list at first occurrence.
  • A term-list entry defines what the term is in one or two sentences. The functional or behavioural detail goes in the body, not in the term list.
  • Even widely recognised proper nouns (industry-standard product names, infrastructure components, etc.) get defined here. Assume the reader does not know them.
  • When defining a compound term, define the constituent words too. If the compound has three words, give all three their own entries — readers cannot be expected to infer one from another.

Diagram conventions

  • Use Mermaid for diagrams. Do not use ASCII art.
  • Every node label is a term that exists in the term list. Do not introduce a new term inside a diagram.
  • Do not put <br/> inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with / or shorten the text to fit one line.
  • For diagrams with four or more nodes, or where any label is long, use graph TD (top-down). graph LR (left-right) collapses long-label graphs into an unreadable horizontal strip.

Granularity of the description

  • Do not gloss details with vague language. Subjects, objects, and verbs must be explicit.
  • A phrase like "A uses B to do X" must specify what A is and why A is needed for X.
  • Avoid vague verbs like "receives" or "passes". Spell out who does what to bring the state about (e.g. "receives the address" → "the platform allocates the address automatically").
  • Do not require the reader to make a leap between steps. Every step's causal connection to the next is explicit.
  • Describe the mechanism in its general form first; tie it to specific named instances afterwards as "in case X, ...". Do not anchor the whole description to a single proper-noun example.

Structure

  1. Term list
  2. Background (why this thing is necessary, or what problem it addresses)
  3. Mechanism (how it works — includes the diagrams)
  4. Concrete steps (commands, procedures, or worked examples)
  5. Current state (where things stand today — for ongoing systems)

Comments

Markdown supported