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/explore-flow-map

Name: explore-flow-map
Author: popoffvg

harness/plugins/work-manager/common/skills/explore-flow-map/SKILL.md

npx skillsauth add popoffvg/dotfiles explore-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 */<input-dir>/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/<input-dir>/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/explore-flow-map

harness/plugins/work-manager/common/skills/explore-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 Jun 2, 2026

$ install --global

skillsauth

npx skillsauth add popoffvg/dotfiles explore-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: Jun 2, 2026, 3:09 AM105.3s1 file scanned

SKILL.md

name:: explore-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 */<input-dir>/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/<input-dir>/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/improve-claude-local

tools

VerifiedTrustedCommunity

Improve a whole CLAUDE.local.md — the private, per-project rules captured from user corrections. Wraps each conditional rule in a <task-relevant> block so it only surfaces for matching work, merges duplicates, generalizes one-off facts, drops stale entries, and routes raw project facts to engram. Use when the user says "improve claude.local", "clean up the local rules", "claude.local is bloated", or after the Stop hook has appended many rules.

2SKILL.mdUpdated Jun 25, 2026

popoffvg/improve-claude-local

popoffvg/workflow

testing

VerifiedTrustedCommunity

WM pipeline and conventions shared across all phases. Agents must read this before spec, impl, or verify work.

2SKILL.mdUpdated Jun 19, 2026

popoffvg/code

development

VerifiedTrustedCommunity

One entry point for spec writing, implementation, and bug fixing. Default is new (write spec → grill loop → produce notes → author TODO bodies). Other subcommands: verify (audit), revise (sync to shipped), prototype (settle a decision), code-map (diagram), impl (execute one TODO), fix (analyze cause, correct thoughts, fix behavior), help (this page). Invoke as /code <subcommand>.

2SKILL.mdUpdated Jun 19, 2026

popoffvg/red-green-refactor

development

VerifiedTrustedCommunity

Red-Green-Refactor cycle for bug fixes. Before fixing a bug, first write a failing test that reproduces it (Red), then make the minimal change to pass (Green), then clean up the code (Refactor). Use on any bug fix, error correction, failing test repair, or when user says "fix this bug".

2SKILL.mdUpdated Jun 18, 2026

popoffvg/red-green-refactor

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/work-manager/common/skills/explore-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/explore-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/improve-claude-local

popoffvg/workflow

popoffvg/code

popoffvg/red-green-refactor

popoffvg/explore-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/improve-claude-local

popoffvg/workflow

popoffvg/code

popoffvg/red-green-refactor

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