agentsclimarketplace

Generate diagram spec

Skill ZacharySBrown/omni-tools/skills/generate-diagram-spec

Research a codebase, file, or concept and produce a create_diagram JSON spec with planned layoutFrom its SKILL.md

Install
npx -y skills add ZacharySBrown/omni-tools --skill generate-diagram-spec

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.0 KB, as published. Nobody here has run it

/generate-diagram-spec — Generate a create_diagram JSON spec from a codebase, file, or concept

When to use

When you need to produce a structured diagram specification before rendering. This is the thinking step — use it before calling create_diagram. Always use this skill when creating non-trivial diagrams.

Input modes

The user will provide one of three types of input. Detect which mode applies:

Mode A: Directory or repo

"Diagram the architecture of src/core/" "Create a diagram of this repo" "Show me how the auth module works"

Mode B: Single file with context

"Diagram this config file" (with file path or pasted content) "Here's our pipeline definition, diagram it" "Visualize this YAML/JSON/Python file"

Mode C: Concept with guidance

"Diagram how RLHF training works" "Create a diagram showing the 4-tier flag resolution" "Visualize a transformer encoder block"

The user may also provide guidance narrowing the focus:

"Focus on the data flow, not the error handling" "Show the public API surface, skip internals" "Include the plugin system"

Process

1. Research (depth depends on input mode)

Mode A — Directory/repo exploration:

  1. Start with the entry point: README.md, package.json/pyproject.toml, main index file
  2. Map the module structure: ls or glob the directory, identify layers/packages
  3. Read key files: entry points, core types/models, main orchestrator
  4. Trace the primary data flow: what comes in, what transforms it, what goes out
  5. Identify boundaries: external inputs, outputs, plugin points, config
  6. If the user gave guidance (e.g., "focus on the API layer"), filter to only relevant modules

Mode B — Single file analysis:

  1. Read the file completely
  2. Identify the entities it defines (classes, functions, config blocks, stages)
  3. Identify relationships (imports, calls, references, data flow)
  4. If it's config (YAML/JSON): each top-level key or section is likely a node
  5. If it's code: classes/modules are nodes, method calls/imports are connections
  6. If the user provided additional context, use it to determine which parts matter

Mode C — Concept with guidance:

  1. Use your knowledge of the concept to identify the standard components
  2. If the user referenced specific code/docs, read those for accurate details
  3. Map the canonical flow (e.g., for RLHF: pretrain → SFT → reward model → alignment)
  4. Identify what makes this particular take interesting (the user's specific variant/implementation)

2. Identify entities

For each entity, determine:

Entity: [name]
  Role: encoder | decoder | attention | input | output | intermediate | neutral
  Label: [short display text — max ~20 chars per line]
  Sublabel: [secondary text — class name, description, details]
  Shape: rounded_rectangle | diamond | circle | pill | annotation
  Category: core | input | output | annotation | decision

Role assignment heuristics:

  • encoder — primary processing components (blue)
  • decoder — secondary processing, output generation (pink)
  • attention — decision-making, routing, selection, configuration (warm yellow)
  • input — data sources, config files, user input (light blue-gray)
  • output — results, exports, final products (green)
  • intermediate — internal state, intermediate results (light pink)
  • neutral — labels, annotations, grouping elements (gray)

3. Identify connections

For each relationship:

[source] → [target]
  Type: straight | orthogonal | curved
  Label: [optional — verb or data name: "sends", "config", "validates"]
  Style: default | highlight | dashed (dashed = optional/plugin)

Connection heuristics:

  • Data flow: solid lines with labels describing what flows
  • Control flow: solid lines, label with action verb
  • Optional/plugin: dashed lines
  • Bidirectional: use style: "bidirectional" sparingly

4. Plan the spatial layout

Determine diagram type from the entity graph:

  • Linear chain → vertical pipeline (most common)
  • Fan-out from center → hub-spoke
  • Binary branching → flowchart/decision tree
  • Multiple parallel chains → swimlanes (side-by-side vertical pipelines)

Vertical pipeline (most common):

Main column:    x=350, width=220-280
Input column:   x=60,  width=180-200  (data sources feeding into main)
Annotation col: x=680, width=200-220  (notes, loss functions, metadata)
Row spacing:    y += 170-200 per stage
Stage labels:   positioned ABOVE their target node (y = node.y - 30)

Horizontal pipeline:

Main row:      y=120
Column spacing: x += 230 per stage
Return row:    y=260 (for loops/feedback)
Width:         160-200px per node

Hub-spoke:

Center:     (400, 280)
Satellites: radius ~250px, distributed by category

Key spacing rules:

  • Minimum 50px gap between adjacent node edges
  • Pre-check text overflow: width >= longest_line_chars * font_size * 0.6 + 32
  • Never place annotations between two nodes — they get sandwiched
  • Title annotation: y=10-30, font_size=20-22
  • Keep total canvas under 1000x900 for single diagrams

5. Produce the spec

Output a complete JSON spec ready for create_diagram:

{
  "title": "Diagram Title",
  "style_preset": "illustrated-technical",
  "layout": "manual",
  "save_path": "<ask user or use known project path>",
  "nodes": [
    {
      "id": "unique_id",
      "label": "Display Name",
      "sublabel": "Secondary text",
      "role": "encoder",
      "shape": "rounded_rectangle",
      "width": 220,
      "height": 70,
      "x": 350,
      "y": 50,
      "font_size": 16
    }
  ],
  "connections": [
    {
      "from": "source_id",
      "to": "target_id",
      "line_type": "straight",
      "label": "optional"
    }
  ]
}

6. Present for review

Before rendering, present a summary so the user can adjust:

## Proposed: [Title]

**[N] nodes, [M] connections** | Style: [preset] | Layout: [type]

| ID | Label | Role | Size | Position |
|----|-------|------|------|----------|
| ... | ... | ... | WxH | (x, y) |

### Connections
| From → To | Type | Label |
|-----------|------|-------|
| ... | ... | ... |

Shall I render this, or adjust anything first?

If the user approves, proceed to /diagrammer-create-diagram to render, review, and export.

Rules

  • Research depth matches input mode — don't over-read for a single file, don't under-read for a repo
  • Respect user guidance — if they say "focus on X", only diagram X
  • Always use manual layout — auto layout produces poor results
  • Pre-check text widths — estimate before assigning node widths
  • Keep node count under 15 — split complex systems into multiple diagrams
  • Use semantic roles consistently — same type of component gets the same role across diagrams
  • Annotations are invisible boxes — opacity: 0, shape: "annotation", placed outside the flow

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.