English · 简体中文

Visualink

Turn difficult technical concepts into interactive maps you can actually understand.

Visualink is an Agent Skill and structured renderer for anyone learning an unfamiliar technical concept. Ask in your own words and get a direct answer, a complete visual map, and the related concepts you may not have known to ask about. When you say who you are, Visualink adapts the explanation to that role.

Try the live demo → · Same concept, different roles · Install Visualink · View the Skill

Why Visualink

This before/after uses one example question — "What is Kubernetes?" — to show the difference. Visualink is not limited to Kubernetes or to infrastructure.

Ask without this skill, and you get a long, accurate explanation. The terms are all there — Pod, Node, Cluster, Service — but you still have to assemble the picture yourself.

Use Visualink, and the same question becomes a map you can scan, replay, and keep.

Before Without Visualink: a wall of text. You finish reading, but still cannot see how the pieces nest, who talks to whom, or why the system exists.

After With Visualink: a map you can keep. Same question. Now the answer, the whole system, and the path through it are visible at once. Open the live Kubernetes example.

Kubernetes is only the demonstration. Ask about networking, AI systems, developer tools, or another concept with components and a flow, and you should get the same kind of map.

The right explanation also depends on who is learning. Visualink adapts the mental model, terminology, depth, examples, and learning path to your role.

That is the difference Visualink is built for:

• Answer first — understand the core idea in one or two sentences.
• See the whole system — begin with the complete map, not an isolated fragment.
• Learn top-down — move through guided chapters only when you are ready.
• Discover the missing questions — understand the components, dependencies, boundaries, and flows you did not yet know to ask about.
• Explain it for your role — if you say who you are, Visualink adapts the answer and map, and explains why the concept matters in that work. If you don't, you still get a clear general explainer.
• Keep the mental model — copy or download the diagram as an image.

How it works

Visualink separates explanation from presentation:

User request
↓
Agent reasons about the concept and audience
↓
VisualinkSpec 1.0 (semantic JSON)
↓
Validation + automatic layered layout + shared renderer
↓
Standalone interactive HTML

The spec contains concepts, semantic nodes and edges, boundaries, chapters, and audience relevance—not pixel coordinates, CSS, SVG paths, or JavaScript. One dependency-free renderer owns nested compound layout and interaction, so explainers stay consistent while their mental models remain concept- and role-specific.

Quick start

1. Install the skill

Install Visualink with one command:

npx skills add jessiedengjie/Visualink

The installer detects supported agents and places the skill in the correct location. It supports Cursor, Claude Code, OpenAI Codex, and other Agent Skills-compatible tools.

Manual installation

Clone or download this repository, then copy the Skill into your agent's personal directory:

• Cursor: ~/.cursor/skills/visualink/
• Claude Code: ~/.claude/skills/visualink/
• OpenAI Codex: ~/.agents/skills/visualink/

# Replace this with one of the directories listed above.
SKILL_DIR="$HOME/.cursor/skills/visualink"
mkdir -p "$SKILL_DIR"
cp -R .cursor/skills/visualink/. "$SKILL_DIR/"

For project-only use, copy the Skill into .cursor/skills/visualink/, .claude/skills/visualink/, or .agents/skills/visualink/.

Download the packaged Skill ZIP if your agent accepts uploaded Skill bundles.

2. Ask a normal question

Use Visualink to explain [a technical concept] to me.

If you do not name a role, Visualink uses a general technical-learner default.

You can also say who you are:

Explain Kubernetes for a Customer Success Manager.

I'm a product manager. Help me understand OAuth.

Explain RAG to me as a solutions architect.

3. Open the result

Visualink creates a VisualinkSpec, validates it, renders one portable HTML file, and opens it in your browser. No frontend framework, backend service, or design knowledge is required to view the result.

Explain it for my role

The right explanation depends on who is learning. Visualink adapts the mental model, terminology, depth, examples, and learning path to your role.

Ask "Explain what LiteLLM is" with no role, then ask again as a Customer Success Manager. You should not get the same map.

The role changes what Visualink emphasizes, which components become primary nodes, how chapters are ordered, how deep the terminology goes, and why the concept matters in that work. It does not invent a different system.

Compare the same concept:

• What LiteLLM is — no role specified: one OpenAI-compatible interface, used as a Python library or as a proxy.
• LiteLLM for a Customer Success Manager — LiteLLM as the customer's AI gateway: where it sits, virtual keys, spend, and reliability, plus a Why this matters for a Customer Success Manager section.

Informal context is enough. You do not have to use a job title:

I am a Customer Success Manager. Explain what LiteLLM is.

What you get

Every explainer is designed around the same learning flow:

1. A direct definition of the concept, in language that fits the audience
2. The complete system map for that audience — not one generic diagram with different captions
3. Numbered chapters that reveal the system from that learner's starting point
4. Labeled connections that explain what moves where
5. When a role is given, a "Why this matters for [role]" section
6. Short cards covering structure, neighboring concepts, and purpose
7. Hover explanations, zoom, pan, and guided playback
8. Light and Dark themes
9. Copy image and Download PNG

Structured renderer workflow

Contributors can validate, render, and preview specs directly:

npm run visualink -- validate examples/rag.json
npm run visualink -- render examples/rag.json
npm run visualink -- dev examples/rag.json

Rendered files are written to dist/ by default. They inline the shared CSS and runtime and remain fully portable after generation. See the VisualinkSpec contributor guide and the public JSON Schema.

The repository includes structured examples for Kubernetes, LiteLLM (general and Customer Success), RAG, and OAuth. The three existing root Kubernetes HTML files remain unchanged as migration and regression references; new renderer output lives under dist/. The LiteLLM HTML files at the repository root are the live demos linked above.

The Visualink approach

Precise before comprehensive

The first explanation must answer the question. Related concepts come afterward and only when they help build the mental model.

A map, not decoration

Nodes represent essential actors. Boundaries show containment. Arrows have directions and verb labels. Colors consistently identify semantic categories.

Complete first, guided second

The default view shows the full picture. Chapters provide a learning path without pretending the selected fragment is the entire system.

Friendly without becoming inaccurate

Plain language and short metaphors help with orientation, but technical relationships remain explicit and verifiable.

Refine it in conversation

You do not need to describe CSS or diagram syntax. React to what you see:

The outer system boundary is too faint in Dark mode.

Make the Light theme brighter and the arrows easier to follow.

Explain the central concept before expanding to its dependencies.

The diagram feels too square. Use softer corners.

Visualink should change only the relevant part, preserve working interactions, and verify both themes after shared visual changes.

Compatibility

The skill uses the portable SKILL.md Agent Skills format.

• Cursor — personal or project skills
• Claude Code — personal or project skills
• OpenAI Codex — personal (~/.agents/skills) or repository (.agents/skills) skills
• Other coding agents — point the agent to the skill file if it can read local files or GitHub repositories

Browser-based verification and image export testing depend on the tools available to the agent.

Repository structure

Visualink/
├── .cursor/skills/visualink/
│   ├── SKILL.md                        # Spec-first Agent Skill
│   ├── schema/visualink.schema.json    # VisualinkSpec 1.0 contract
│   ├── lib/                            # Validation, layout, and rendering
│   ├── renderer/                       # Shared styles and browser runtime
│   └── bin/visualink.mjs               # validate, render, and dev CLI
├── examples/                           # Semantic VisualinkSpec sources
├── dist/                               # Generated standalone HTML
├── tests/                              # Dependency-free Node tests
├── docs/visualink-spec.md              # Contributor guide
├── kubernetes-*.html                   # Legacy/reference demos
├── litellm*.html                       # Live LiteLLM role demos
├── package.json                        # Local CLI and scripts
└── README_ZH.md                        # Chinese onboarding

Design principles

• Start from the learner, not the system vocabulary.
• Adapt the map to the learner's role; do not reuse one generic architecture.
• Show only the components needed to understand the question.
• Use visual hierarchy to reduce cognitive load.
• Make every important connection directional and named.
• Keep semantic reasoning in the spec and presentation behavior in the renderer.
• Prefer one self-contained file that is easy to open and share.
• Verify the experience in the browser instead of trusting source code alone.

Support Visualink

If Visualink helps you understand a difficult concept, star the repository so you can find it again—and share the map you created.