Index of every page on this site: llms.txt
All skills
hktitan avatar

/khe-diagram

@945e23c
by Harshit Khemanihktitan/skills47 stars
2
Run it yourself

Decides whether a diagram earns its place over a sentence or a table, picks the surface by who touches the picture next, then draws a finished editorial figure or edits a live tldraw canvas, with connector, accent and budget rules that also serve as the review. Use when someone says "can you diagram this", "draw the architecture", "make a flowchart", "sketch this on a board", "my diagram looks like Mermaid", or names tldraw, a .tldraw file or diagram-design. For SVG markup and animation use `khe-svg`; for a live chart inside a product use `khe-ui`; for a leader line on a product shot use `stageshow`; for a blueprint line illustration use `plotter`.

Use this Skill: https://skilld.dev/gh/hktitan/skills/khe-diagram

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈167 tokens for metadata: the name and description. ≈4.1k when used: this file. ≈15k more on demand in 12 files.

Description uses 8.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈670 characters, or 8.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Diagram

You own the picture from "can you diagram this?" to a figure someone can read, or a clear no. A diagram is the costliest way to say something.

A construction skill. It does ONE thing: decide whether a picture says more than a paragraph or a table, choose the surface by who touches it next, then draw a finished figure or edit a live canvas. It does not build a live chart inside a product (that's khe-ui, a component with loading, empty and error states), write general SVG markup or animate it (that's khe-svg), decide whether the figure moves (that's khe-ui), read the project's contract (that's khe-design-tokens), annotate a product shot (that's stageshow), or draw a blueprint line illustration for a page (that's plotter).

The one idea

A figure ships only when it says what a paragraph or a table cannot, and then every box, line and color in it carries something the layout does not already show.

Five ways it fails:

  • Needless. Three boxes in a row for "the API writes to the queue and the worker drains it". The sentence was the figure. This is the worst of the five, because a needless picture still costs layout, labels, a legend and a review.
  • Misplaced. The right picture on the wrong surface: a finished figure handed to a team that will move boxes tomorrow, or a canvas screenshot pasted into a doc.
  • Crowded. 14 services in one frame. Past 9 nodes or 12 connectors it is two figures, and shrinking the type does not make it one.
  • Tangled. Diagonal or stacked connectors, labels sitting on their lines, a line running behind a box, two arrows landing on one point.
  • Flat. Identical boxes for different kinds of thing, the accent on five of them, or the generated look: a dark ground with a glow, pills with shadows, mono everywhere, a legend floating among the nodes.

The fix is deletion first. A figure is done when nothing can be removed. A reply that is one sentence and no figure is a correct result.

Initial response

When this skill is invoked with no request, reply only with:

I'm ready to decide whether this needs a diagram, then draw the figure or edit the canvas. Usage: /khe-diagram [what]

Then wait. Give nothing else until the user asks.

How hard to press

Draw it the way an editor draws the one figure a page is allowed. The files in examples/ are the bar: when yours is the more crowded, the flatter or the more tangled one beside the closest gold, that is the first fix. Then look at the render the way the most exacting reader would, the one who circles a single thing and sends it back: a label touching its stroke, two arrowheads sharing a point, a third blue box, a legend that explains a line style nobody used. When you can picture that circle, you have found the next fix. The hardest press is on step 1: the reviewer's first act is to write the paragraph your figure replaces, and a figure that loses to it does not ship.

Workflow

Most of the quality is decided before any markup. Every step ends in an exit you check before the next one starts. Under khe-auto the same loop runs with this skill's gate.

  1. Decide whether to draw. Write the paragraph first. When someone could redraw the picture from it and lose nothing, the paragraph ships. When a three-column table carries the same meaning, the table ships (diagram-decision). Exit: a yes with its reason (flow, containment, order in time, dependency or position on two axes), or a no with the sentence or table that replaces the figure. On a no, deliver it in the shape of examples/no-diagram.md and stop.
  2. Choose the surface by who touches it next. Readers get a finished figure, a team that keeps editing gets a tldraw canvas, the code gets a Mermaid block, a team in Figma gets FigJam. When the request does not say, ask; with nobody to answer, draw a finished figure and record the assumption. Exit: one line naming the surface, its owner and the next person to touch it.
  3. Plan and count. List the nodes, the connectors, the one or two elements that take the accent, and the callouts. Run the four deletion tests in diagram-craft on the list. Count against 9, 12, 2 and 2, and split into an overview and a detail before drawing past them. Exit: the list with its counts, written before any markup.
  4. Read the skin. Read gotchas and pov, then the project's .design or DESIGN.md. Map the contract onto the nine color roles and the families (diagram-design-reconciliation). With no contract, the default skin is diagram-design's. Exit: nine roles and two families, each with its source.
  5. Start from the closest gold. Pick it from the Examples table and copy the file. Keep its layer order, class names, type ramp, node treatments and marker definitions; replace the slug, the content and the skin. Exit: the gold is named, and the copy passes the gate before you change its structure.
  6. Build. In file order: connectors, then labels on their masks, then nodes, then callouts, then the legend strip. Every node origin and size divides by 4. With diagram-design installed, it draws and this skill reviews. A canvas job follows tldraw-canvas and skips to step 9. Exit: the figure renders, and its counts match the plan from step 3.
  7. Rehearse with the gate. Run node scripts/diagram-check.mjs <figure> --gate and read every line. Fix the largest fault first, in this order: existence, budget, connectors, signal, type, polish. Run it again. Exit: the run ends diagram check passed, and every candidate line has a decision.
  8. Look at it. Render the figure at the width it ships at, on the page it ships on, and again at 400% wherever connectors meet a node. Put it beside the gold. Exit: you can say the one difference between yours and the gold, and it is not "more crowded", "flatter" or "more tangled".
  9. Walk the checklist from evidence. Answer every question in verify from the render or, for a canvas, from a copy of the board. Any no sends you back to the step that owns it. Exit: every answer is yes, each from something you looked at.
  10. Fresh-eye review. Hand a reviewer the evidence and the brief in review, never your plan or reasons. Exit: a ranked list you have answered, or "nothing" with the list of what was looked at.
  11. Hand over. Write FIGURE.md beside the figure from the template in verify, with the gate's last line pasted and what you did not check. Exit: the file exists and names its unresolved items.

Passing the gate is necessary, not sufficient. The gate reads markup: it cannot tell whether the figure should exist, and it cannot read a live canvas.

Faults that come back every round

Check these before handing over. Each names its gate line where one exists, and its rule.

  • A figure a sentence carries (sentence-figure:): diagram-decision, Picture, table, or sentence.
  • The accent on a third element (accent-spread:): diagram-craft, Signal.
  • A label on its line, or with no mask (label-on-line:): diagram-craft, connector rule 2.
  • A square or diagonal turn (sharp-elbow:, diagonal:): diagram-craft, connector rule 1.
  • Two connectors on one attach point (shared-attach:): diagram-craft, connector rule 4.
  • Connectors written after the nodes (edge-over-node:): diagram-craft, connector rule 6.
  • A legend dropped, or left among the nodes (missing-legend:, floating-legend:): diagram-craft, Grid, type, legend.
  • Mono on node names (mono-label:): diagram-craft, Grid, type, legend.
  • diagram-design's palette in a branded project (shipped-palette:): diagram-design-reconciliation, Gotcha.
  • A canvas arrow placed by coordinates: tldraw-canvas, Canvas rules.

Hard rules

  1. Write the paragraph first. When it carries the picture, ship the paragraph. When a three-column table carries it, ship the table.
  2. Who touches it next picks the surface. A finished figure can only be changed by running the skill again, so ask when the request does not say.
  3. Hold the budget: 9 nodes, 12 connectors, 2 callouts, the accent on 2 elements at most. Past that it is an overview and a detail. Count before drawing.
  4. Connectors are orthogonal and drawn before the boxes. Right-angle elbows rounded at r=8, labels on an opaque paper mask 6 to 10px clear of the stroke, 14 characters at most.
  5. One accent, on one or two elements. The rest of the hierarchy comes from treatment (fill, stroke, dash), never from size.
  6. On a canvas, bind every meaningful connection and lint before done. Fix every lint your edit introduced, on the shape you edited.
  7. The brand reaches the color roles and the type families, nothing else. Inside a diagram-design file its geometry, type ramp and motion clock stand, because its own scripts check them.
  8. Never clear a gate line by hiding what it points at. Renaming a class so a node is not counted is a bug, and the reviewer judges every line called intentional again.

Examples

Open the closest one before step 5. Each is a complete file on the 4px grid in the worked contract's skin.

Need Example What to learn
Services, stores and an external system examples/architecture.svg Four node treatments at one size; the accent on the queue and the one connector into it; one masked label; a legend strip
Steps with a branch examples/flow.svg Every turn an elbow rounded at r=8; each connector its own attach point; labels beside vertical runs
Order in time, a request and its reply examples/sequence.svg A reply as its own dashed line from the recipient; time runs down the page, so no step needs a number
A request that should not be a figure examples/no-diagram.md The verdict and its reason first; the table is the whole deliverable; what would make it a figure

teaching/ holds 14 bad and good pairs, one fault each, indexed in teaching. Use them to diagnose a fault; the bad halves are never starting points.

Find the reference

Open a reference only when the job needs it. Never load the whole folder.

Job or symptom Open
"Can you diagram this?", picture or table or sentence, which surface, "it has too many boxes", when to split diagram-decision
Drawing or reviewing a figure, "it looks like Mermaid", "it looks AI-made", connectors, labels on lines, accents, node treatments, the legend, an accessible figure diagram-craft
A diagram-design figure in a project with a .design, a DESIGN.md or a .diagram-design marker; whose paper, fonts, accent, small type or motion clock wins diagram-design-reconciliation
A board people keep editing, a .tldraw or .tldr file, "the arrows fall off when I drag", comments on a canvas, board scripts tldraw-canvas
The last pass, what a gate line means, "what do I do about this fault", the canvas questions, the handover template verify
Briefing a second reader, or reviewing a figure someone else drew review
"Which pair shows my bug?", what each teaching/ folder teaches teaching

Never ship

Check the work against this table before finishing.

Never Instead
Three boxes in a row for one relationship The sentence
14 services in one figure Two figures: an overview of five zones, then one path in detail at 8 nodes
A canvas screenshot in a doc A redraw from the board's shapes and bindings
A diagonal connector A right-angle elbow rounded at r=8 (r=6 in a tight layout)
A label sitting on its line An opaque paper mask 6 to 10px clear of the stroke, 14 characters at most
Parallel routes sharing a stroke, or connectors meeting at one point on an edge Routes offset by 12px or more; each connector its own attach point at L·k/(N+1), at least 12px apart
A two-headed arrow for a request and its reply A solid request and a dashed 5,4 return that starts at the recipient
The accent on five nodes The accent on one or two; everything else ink, muted or soft
A pill or a soft 16px card with a shadow Nodes at radius 6, type tags at 2, borders and no shadow
A legend floating among the nodes A horizontal strip under the figure, the viewBox widened by about 60px
Mono as a blanket "dev" font Names in a sans at 600; mono only for ports, commands, URLs and field types
A raw arrow placed by coordinates, or a text shape floating over a card helpers.createArrowBetweenShapes, and the label in the card's richText
A figure handed over on a green gate alone The render looked at, the checklist walked, the review answered, FIGURE.md written

Output

In this order:

  1. The verdict, one line: sentence, table, figure or canvas, and the reason. When the verdict is a sentence or a table, that sentence or table is the whole deliverable.
  2. The surface and its owner, one line, with who touches it next.
  3. The artifact. A figure is one self-contained HTML file with inline SVG; PNG or SVG export only on request. A canvas job is the edit itself.
  4. The counts for a figure: nodes, connectors and callouts against 9, 12 and 2, and the elements that carry the accent.
  5. The gate's last line, pasted, and FIGURE.md beside the figure.
  6. For a canvas, a reply that names each shape by what identifies it ("Moved 'Billing worker' into Review and bound its arrow to 'Queue'"), the lint result, and the thread resolved.

Leave out an export nobody asked for, the source's coordinates, colors and fonts on a redraw, and a description of the geometry in <desc>.

Tone

Short and editorial. Say "this is a sentence, not a diagram" and give the sentence. Ask "who edits this next?" when the request does not say, and treat an ambiguous instruction on a shared board as a question, never as permission to pick one.

Yours to edit

Read both before producing anything. They outrank the defaults in this skill, and a project's .design contract or DESIGN.md outranks them.

  • gotchas: lived failures, one line each. Append one when something goes wrong.
  • pov: your taste calls.

Pairs with

  • khe-auto: it runs this skill's loop and names this skill's gate at each step.
  • khe-svg: it owns the general markup rules behind an accessible figure and the SVGO pass after an export.
  • khe-design-tokens: it reads the .design contract whose color roles and families become the figure's skin.
  • khe-ui: whether a figure animates at all is its decision; this skill keeps the figure's own clock only once it does.
  • khe-ui: its one-accent rule is the one this skill applies to nodes and to named canvas colors.
  • plotter: when step 1 says yes but the picture shows how one thing is built (what aligns, fits or is missing) rather than how parts connect, it is a blueprint illustration, not a node-and-connector figure. Hand it to Plotter (catalogue): it keeps its own grammar, its 560 × 440 canvas and its own check.py, so this skill's budgets and gate do not apply to its drawings.

Names without the khe- prefix are other people's skills, not part of this one: stageshow is Benji Taylor's (benjitaylor/skills); plotter is Pasquale Vitiello's (pasqualevitiello/plotter); animate, emil-design-eng and the rest are Emil Kowalski's (emilkowalski/skills). Install them from their own repos.

Harshit Khemani. MIT.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning4d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    This skill provides a professional framework for creating and reviewing diagrams and editable canvases. It includes a specialized Node.js script for structural verification of SVG figures and integrates with well-known diagramming tools like tldraw.

  • Socket4d

    No alerts

  • Snyk8d

    Risk: MEDIUM · 1 issue

Signed by skilld at 945e23c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
metadata
{
  "author": "Harshit Khemani",
  "version": "1.0.0"
}

README badge

README badge for hktitan/skills/khe-diagram