Adoption

Agent Skills are supported by leading AI development tools.

VS Code Gemini CLI GitHub Goose Amp Cursor Claude Code Letta OpenCode Claude OpenAI Codex Factory VS Code Gemini CLI GitHub Goose Amp Cursor Claude Code Letta OpenCode Claude OpenAI Codex Factory

popoffvg/flow-map

Name: flow-map
Author: popoffvg

harness/plugins/exploration/claude/skills/flow-map/SKILL.md

npx skillsauth add popoffvg/dotfiles flow-map

Clean

TrivyContainer and dependency vulnerability scanner

Clean

SemgrepStatic code analysis for vulnerabilities

Clean

mcp-scan (Snyk)Model Context Protocol security validation

Skipped

Snyk (dep)Open source security scanning

Skipped

Socket.devSupply chain security analysis

Skipped

VirusTotalMulti-engine malware detection

Skipped

CrowdStrikeAdvanced threat intelligence

Skipped

OSV-ScannerOpen Source Vulnerability database check

Skipped

OWASP Dep-Check

Purpose

Produce one self-contained HTML file that:

Lays out every package/component in swimlane columns by kind on a dark canvas (ToDesktop-style architecture diagram).
Lists named actions ("flows") in a sidebar. Clicking a flow:
- dims non-participating packages,
- highlights participants with a colored border in the column's tint,
- draws ordered edges between them with numbered yellow step circles,
- fills a STEPS panel with each edge's payload + source path:line.
Works offline after first load (one CDN script for Cytoscape, no build step).

Input: a JSON document. Output: a single .html file.

Input JSON schema

{
  "title": "MyApp — Architecture & Flows",
  "packages": [
    {
      "id": "web",                       // unique slug used in edges
      "label": "Web Frontend",           // node title
      "sub":   "apps/web",               // optional 2nd line under title
      "kind":  "actor|client|codebase|sdk|backend|external",
      "description": "..."               // shown in tooltips / steps if you add it
    }
  ],
  "flows": [
    {
      "id": "invite-user",
      "label": "Invite new user",
      "description": "...",
      "edges": [
        {
          "from": "web", "to": "api",
          "via": "POST /invites",                  // transport label
          "payload": "{ email, role }",            // 1-line summary
          "source": "apps/web/src/Invite.tsx:84",  // verifiable path:line
          "notes":  "..."                          // optional caveat
        }
      ]
    }
  ]
}

edges[] order is the temporal step sequence — the renderer numbers them 1, 2, 3, ….

Recommended `kind` taxonomy (drives swimlane columns)

| kind | Column label | Tint | | ---------- | ------------------------ | --------- | | actor | ACTORS | #fbbf24 | | client | CLIENT SURFACE | #60a5fa | | codebase | BLOCK / FUNCTION CODEBASE| #34d399 | | sdk | SDK / LIB | #a78bfa | | backend | BACKEND PIPELINE | #f97316 | | external | EXTERNAL SERVICES | #f87171 |

Free to extend — just pick a hex tint and a header label per new kind.

Output

Default path <input-dir>/index.html next to the source JSON (or ${TMPDIR%/}/claude-flow-map/<basename>.html if input is outside a project).

Procedure

Resolve input. If user didn't pass a path, look for the newest ${TMPDIR%/}/claude-explore/*/flows.json or */flow-map/flows.json in .notes/.
Validate. Every edge.from/edge.to resolves to a known package.id. Every flow.id is unique.
Pick output path. mkdir -p if needed.
Write the HTML directly using the Write tool. Do NOT generate the HTML through a bash heredoc — see the bash trap below.
Print the absolute output path. open on macOS may fail under sandbox; tell the user to open the file manually if it does.

CRITICAL — bash traps that ruined past runs

`!` history expansion mangles `<!doctype`

Bash performs history expansion on ! even inside single-quoted heredocs on some setups. Result: every <! becomes <\!, the browser stops parsing the file as HTML, and you get a blank page with literal <\!doctype html> text at the top.

Fix: never write the HTML through bash << 'EOF' or python3 -c "..." piped through bash. Build the full HTML string in memory and pass it to the Write tool. The Write tool bypasses the shell — bytes land verbatim.

Sanity-check after writing:

head -c 16 path/to/index.html   # must print: <!doctype html>

`</` inside an inlined JSON string closes the `<script>` tag

When embedding a JSON literal between <script> tags, any </ substring in your data terminates the script element. Either:

Inline the data as a JS object literal (write { … } directly, not a JSON string), or
JSON-stringify and replace </ → <\/ in the resulting string.

The first form is what this skill uses.

Other gotchas

0-height canvas. A nested CSS grid needs min-height:0 on its row track and min-height:300px on #cy or Cytoscape draws nothing.
Function-valued styles. 'background-color': ele => … is brittle across Cytoscape versions. Precompute the color into node data and use 'background-color': 'data(color)'.
CDN drift. Pin the version: [email protected].
open fails under the agent sandbox. That's not your bug; just print the path.

Implementation reference (proven template)

The skill's HTML is built around these ideas (paste/adapt — keep ~300 lines):

Layout: CSS Grid, two columns — 1fr 340px. Left = canvas, right = sidebar.
Theme: dark (#0a0a0a bg, #e5e7eb text, #fbbf24 accent, #262626 borders).
Cytoscape:
- One compound node per column (kind), styled with a dashed border, a small uppercase header label colored in the column tint, and compound-sizing-wrt-labels: include.
- Each package node has parent: <column-id>, fixed position: { x, y }, layout: { name: "preset" }. Columns auto-size to fit.
- Edges use curve-style: unbundled-bezier with control-point-distances for the curved orange look. target-arrow-shape: triangle.
- Numbered step bubbles = edge label with text-background-color: #fbbf24, text-background-shape: round-rectangle, text-background-padding: 4px, plus a dark text-border for contrast.
- Self-loops: add .loop class with loop-direction / loop-sweep.
Sidebar:
- Top half: button per flow. Active button gets the yellow accent border.
- Bottom half: numbered list. Each step row = <div class="num">N</div> + a block with from → to, the via label, payload (monospace), source (smaller monospace), and notes (in #fde68a).
Behavior:
- On flow select: cy.edges().remove(), recompute participants set, toggle .hot / .dimmed on package nodes, add edges with num: String(i+1), re-render the STEPS panel.
- Default selection: the cross-cutting "end-to-end" flow if present; otherwise the first flow.

A complete working copy lives at ~/Documents/git/mil/tasks/MILAB-6225-identity-propogation/.notes/flow-map/index.html — copy-paste and swap the data block when bootstrapping new diagrams.

Update / re-render

Re-run the skill — it overwrites the previous HTML in place. The JSON beside it (flows.json) is the source of truth; keep them next to each other so the user can edit JSON and re-render.

Limits

Sweet spot: ≤ 30 packages, ≤ 8 flows, ≤ 12 edges per flow.
Beyond that, swimlane Y-positions need manual tuning (consider auto-spacing children within each compound column by flow.edges participation order).
The payload field is a 1-line summary by design. Long structures belong in the linked source.

popoffvg/flow-map

harness/plugins/exploration/claude/skills/flow-map/SKILL.md

Render an interactive single-page HTML that visualizes packages/components and the cross-package flows of named actions (e.g. "Invite new user", "todesktop build"). Driven by a JSON document. Use when the user says "flow map", "render flows", "interactive workflow html", "visualize package interactions", or has a flows.json from the `explore` skill they want to view.

2 stars

development

Updated May 20, 2026

$ install --global

skillsauth

npx skillsauth add popoffvg/dotfiles flow-map

Install this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.

Security Scan Results

3 of 9 scanners reported clean

Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.

Scanners Passed

Scanners in report

Clean

TrivyContainer and dependency vulnerability scanner

95%

Clean

SemgrepStatic code analysis for vulnerabilities

95%

Clean

mcp-scan (Snyk)Model Context Protocol security validation

95%

Skipped

Snyk (dep)Open source security scanning

50%

Skipped

Socket.devSupply chain security analysis

50%

Skipped

VirusTotalMulti-engine malware detection

50%

Skipped

CrowdStrikeAdvanced threat intelligence

50%

Skipped

OSV-ScannerOpen Source Vulnerability database check

50%

Skipped

OWASP Dep-Check

50%

Last scanned: May 20, 2026, 4:40 AM107.2s1 file scanned

SKILL.md

name:: flow-map
description:: Render an interactive single-page HTML that visualizes packages/components and the cross-package flows of named actions (e.g. "Invite new user", "todesktop build"). Driven by a JSON document. Use when the user says "flow map", "render flows", "interactive workflow html", "visualize package interactions", or has a flows.json from the `explore` skill they want to view.
argument-hint:: path to flows.json (defaults to $TMPDIR/claude-explore/<latest>/flows.json)

Purpose

Produce one self-contained HTML file that:

Lays out every package/component in swimlane columns by kind on a dark canvas (ToDesktop-style architecture diagram).
Lists named actions ("flows") in a sidebar. Clicking a flow:
- dims non-participating packages,
- highlights participants with a colored border in the column's tint,
- draws ordered edges between them with numbered yellow step circles,
- fills a STEPS panel with each edge's payload + source path:line.
Works offline after first load (one CDN script for Cytoscape, no build step).

Input: a JSON document. Output: a single .html file.

Input JSON schema

{
  "title": "MyApp — Architecture & Flows",
  "packages": [
    {
      "id": "web",                       // unique slug used in edges
      "label": "Web Frontend",           // node title
      "sub":   "apps/web",               // optional 2nd line under title
      "kind":  "actor|client|codebase|sdk|backend|external",
      "description": "..."               // shown in tooltips / steps if you add it
    }
  ],
  "flows": [
    {
      "id": "invite-user",
      "label": "Invite new user",
      "description": "...",
      "edges": [
        {
          "from": "web", "to": "api",
          "via": "POST /invites",                  // transport label
          "payload": "{ email, role }",            // 1-line summary
          "source": "apps/web/src/Invite.tsx:84",  // verifiable path:line
          "notes":  "..."                          // optional caveat
        }
      ]
    }
  ]
}

edges[] order is the temporal step sequence — the renderer numbers them 1, 2, 3, ….

Recommended `kind` taxonomy (drives swimlane columns)

Free to extend — just pick a hex tint and a header label per new kind.

Output

Default path <input-dir>/index.html next to the source JSON (or ${TMPDIR%/}/claude-flow-map/<basename>.html if input is outside a project).

Procedure

Resolve input. If user didn't pass a path, look for the newest ${TMPDIR%/}/claude-explore/*/flows.json or */flow-map/flows.json in .notes/.
Validate. Every edge.from/edge.to resolves to a known package.id. Every flow.id is unique.
Pick output path. mkdir -p if needed.
Write the HTML directly using the Write tool. Do NOT generate the HTML through a bash heredoc — see the bash trap below.
Print the absolute output path. open on macOS may fail under sandbox; tell the user to open the file manually if it does.

CRITICAL — bash traps that ruined past runs

`!` history expansion mangles `<!doctype`

Sanity-check after writing:

head -c 16 path/to/index.html   # must print: <!doctype html>

`</` inside an inlined JSON string closes the `<script>` tag

When embedding a JSON literal between <script> tags, any </ substring in your data terminates the script element. Either:

Inline the data as a JS object literal (write { … } directly, not a JSON string), or
JSON-stringify and replace </ → <\/ in the resulting string.

The first form is what this skill uses.

Other gotchas

0-height canvas. A nested CSS grid needs min-height:0 on its row track and min-height:300px on #cy or Cytoscape draws nothing.
Function-valued styles. 'background-color': ele => … is brittle across Cytoscape versions. Precompute the color into node data and use 'background-color': 'data(color)'.
CDN drift. Pin the version: [email protected].
open fails under the agent sandbox. That's not your bug; just print the path.

Implementation reference (proven template)

The skill's HTML is built around these ideas (paste/adapt — keep ~300 lines):

Layout: CSS Grid, two columns — 1fr 340px. Left = canvas, right = sidebar.
Theme: dark (#0a0a0a bg, #e5e7eb text, #fbbf24 accent, #262626 borders).
Cytoscape:
- One compound node per column (kind), styled with a dashed border, a small uppercase header label colored in the column tint, and compound-sizing-wrt-labels: include.
- Each package node has parent: <column-id>, fixed position: { x, y }, layout: { name: "preset" }. Columns auto-size to fit.
- Edges use curve-style: unbundled-bezier with control-point-distances for the curved orange look. target-arrow-shape: triangle.
- Numbered step bubbles = edge label with text-background-color: #fbbf24, text-background-shape: round-rectangle, text-background-padding: 4px, plus a dark text-border for contrast.
- Self-loops: add .loop class with loop-direction / loop-sweep.
Sidebar:
- Top half: button per flow. Active button gets the yellow accent border.
- Bottom half: numbered list. Each step row = <div class="num">N</div> + a block with from → to, the via label, payload (monospace), source (smaller monospace), and notes (in #fde68a).
Behavior:
- On flow select: cy.edges().remove(), recompute participants set, toggle .hot / .dimmed on package nodes, add edges with num: String(i+1), re-render the STEPS panel.
- Default selection: the cross-cutting "end-to-end" flow if present; otherwise the first flow.

A complete working copy lives at ~/Documents/git/mil/tasks/MILAB-6225-identity-propogation/.notes/flow-map/index.html — copy-paste and swap the data block when bootstrapping new diagrams.

Update / re-render

Re-run the skill — it overwrites the previous HTML in place. The JSON beside it (flows.json) is the source of truth; keep them next to each other so the user can edit JSON and re-render.

Limits

Sweet spot: ≤ 30 packages, ≤ 8 flows, ≤ 12 edges per flow.
Beyond that, swimlane Y-positions need manual tuning (consider auto-spacing children within each compound column by flow.edges participation order).
The payload field is a 1-line summary by design. Long structures belong in the linked source.

Related Skills

popoffvg/test-set-write

testing

VerifiedTrustedCommunity

Use when the user asks to create test sets, enumerate scenarios, generate edge cases, or draft a coverage matrix before implementation.

2SKILL.mdUpdated Jun 2, 2026

popoffvg/test-set-write

popoffvg/test-set-verify

testing

VerifiedTrustedCommunity

Use when the user asks to review, audit, score, or validate test sets for missed cases before execution or merge.

2SKILL.mdUpdated Jun 2, 2026

popoffvg/test-set-verify

popoffvg/test-harness-plugin

tools

VerifiedTrustedCommunity

Test harness plugins in isolation using tmux panes. Runs MCP servers, unit tests, typecheck, and Claude plugin loading. Use when user says "test plugin", "check plugin", "run plugin tests", "validate plugin", or names a specific plugin to test.

2SKILL.mdUpdated Jun 2, 2026

popoffvg/test-harness-plugin

popoffvg/test-bdd

development

VerifiedTrustedCommunity

Guide for designing integration and e2e tests using BDD (Behavior-Driven Development) methodology with Cucumber-style Given/When/Then scenarios. Use when writing or reviewing tests for any service, API, or component. Language-agnostic — covers scenario structure, step notation, assertion principles, async patterns, and common anti-patterns.

2SKILL.mdUpdated Jun 2, 2026

Download

For Claude Desktop. Download once, then upload the file in the app — no terminal needed.

Need help? View full Cowork setup guide →

Install manually

Choose your platform

# Clone the repo
git clone https://github.com/popoffvg/dotfiles.git

# Copy into Claude Code skills folder (global)
cp -r dotfiles/harness/plugins/exploration/claude/skills/flow-map ~/.claude/skills/

Claude Code Skills — official skills path docs.

Repository

popoffvg/dotfiles

2 stars

Compatible with

Claude Code

OpenAI Codex CLI

ChatGPT

Adoption

popoffvg/flow-map

$ install --global

Security Scan Results

SKILL.md

Purpose

Input JSON schema

Recommended kind taxonomy (drives swimlane columns)

Output

Procedure

CRITICAL — bash traps that ruined past runs

! history expansion mangles <!doctype

</ inside an inlined JSON string closes the <script> tag

Other gotchas

Implementation reference (proven template)

Update / re-render

Limits

Related Skills

popoffvg/test-set-write

popoffvg/test-set-verify

popoffvg/test-harness-plugin

popoffvg/test-bdd

popoffvg/flow-map

$ install --global

Security Scan Results

SKILL.md

Purpose

Input JSON schema

Recommended kind taxonomy (drives swimlane columns)

Output

Procedure

CRITICAL — bash traps that ruined past runs

! history expansion mangles <!doctype

</ inside an inlined JSON string closes the <script> tag

Other gotchas

Implementation reference (proven template)

Update / re-render

Limits

Related Skills

popoffvg/test-set-write

popoffvg/test-set-verify

popoffvg/test-harness-plugin

popoffvg/test-bdd

Recommended `kind` taxonomy (drives swimlane columns)

`!` history expansion mangles `<!doctype`

`</` inside an inlined JSON string closes the `<script>` tag

Recommended `kind` taxonomy (drives swimlane columns)

`!` history expansion mangles `<!doctype`

`</` inside an inlined JSON string closes the `<script>` tag